@go-labs-sg/rsvp 0.17.0 → 1.0.0

package/README.md

@@ -135,6 +135,76 @@ rsvp event flow versions list --organization-id org_123 --event-id evt_123
 rsvp event flow resources get --organization-id org_123 --event-id evt_123
 ```
 
+### Registration-flow admission policy
+
+`event flow draft get` returns normalized legacy invitation forms as
+`authentication.mode: "EMAIL_OTP"` with `definition.admissionPolicy: "ROSTER_ONLY"`.
+Carry that independent policy through `event flow draft save`, `event flow publish`,
+and `event flow version activate`; none of those operations silently opens signup.
+The participant-safe `event flow published get` admission manifest also reports
+`admissionPolicy` (`OPEN` for modern definitions without an explicit policy).
+
+Save the complete returned definition with its current `expectedRevision`.
+Omitting `admissionPolicy` preserves the stored draft/publication policy for older
+clients. To intentionally broaden admission, explicitly set it to `"OPEN"` in the
+modern email-auth definition, save, then publish; this remains subject to event
+permissions, audience restrictions, and email-domain policy for new attendees.
+Existing eligible roster attendees keep their existing eligibility rules.
+
+```sh
+rsvp event flow draft get --payload '{"organizationId":"org_123","eventId":"evt_123","flowId":"flow_123"}'
+# Save the complete JSON definition and expectedRevision in flow-draft.json.
+# Keep admissionPolicy: "ROSTER_ONLY" unless the organiser approves open signup.
+rsvp event flow draft save --allow-state-change --target evt_123 --payload "$(cat flow-draft.json)"
+rsvp event flow publish --allow-state-change --target evt_123 --payload '{"organizationId":"org_123","eventId":"evt_123","flowId":"flow_123","expectedDraftRevision":2}'
+rsvp event flow version activate --allow-state-change --target evt_123 --payload '{"organizationId":"org_123","eventId":"evt_123","flowId":"flow_123","flowVersionId":"version_123"}'
+```
+
+Replace illustrative IDs and revisions with current readback values. Deploy API
+policy enforcement before clients; an old API does not understand this field.
+No authentication, consent flags, command names, or credential protocol changes.
+
+### Registration-flow date-limit messages
+
+`DATE` and `DATETIME` custom fields accept optional
+`field.validation.minDateMessage` and `maxDateMessage`: trimmed, non-empty plain
+text of at most 500 characters. Each replaces only its corresponding out-of-range
+explanation. Inclusive `minDate`/`maxDate` bounds, malformed-date errors and
+required-field errors are unchanged; omitted messages keep the existing defaults.
+
+An illustrative DOB validation object is:
+
+```json
+{
+  "maxDate": "2008-01-01",
+  "maxDateMessage": "You must be at least 18 to register for this event."
+}
+```
+
+Age wording is organizer-authored, not a dynamic age rule. Choose the cutoff for
+the event; do not reuse the illustrative date blindly.
+
+Read the full current definition/revision using `event flow draft get`, edit the
+intended field, then pass the complete definition to `event flow preview` and
+`event flow draft save --allow-state-change --target <eventId> --payload <JSON>`.
+Preview/save payloads include `organizationId`, `eventId`, optional `flowId`, and
+`definition`; save also requires `expectedRevision`. Publish separately using
+`event flow publish --allow-state-change --target <eventId> --payload <JSON>` with
+`expectedDraftRevision`. Read back the saved definition with `event flow draft get`
+and verify its compiled participant projection using the authenticated organizer
+`event flow preview` command. Use `event flow versions list` to check immutable
+version/publication identity; `event flow published get` provides public admission
+and publication metadata in normal CLI execution, not the full participant fields.
+It has no participant-session forwarding; the API returns `flow.participant` as
+`null` without matching participant access. Verify the actual published date limits
+and messages through the event's registration flow with a valid participant
+session.
+
+Existing commands forward the definition unchanged to the authenticated shared
+API; no new flags or CLI-only validation are needed. Deploy matching API/web
+support before saving these keys via the CLI; older APIs strip unrecognized
+message keys. No event or published version is updated automatically.
+
 ### Registration-flow image upload lifecycle
 
 Registration-flow images are **named, event-local assets**. Create one with an
@@ -175,6 +245,163 @@ protocol. Reference the finalized asset from the appropriate form choice, then
 save and publish the flow separately when the complete draft is approved.
 
 
+## Stripe payments and external refunds
+
+`payment checkout create` uses the same server-enforced finite reservation policy
+as the web app. New Checkout sessions exclude known slow-settling methods while
+retaining dynamic immediate methods such as cards and PayNow. Existing sessions
+and late-success safeguards are unchanged.
+
+`payment event list` reports completed refund totals including separately
+recorded, verified refunds issued outside RSVP. Pending/failed provider refunds
+do not count, and an external refund never consumes an unrelated app refund
+request. `payment refund` still requires the existing financial/external-write
+gates and original account binding. `payment exception list` remains the place
+to inspect unresolved payment exceptions. Existing command inputs and gates are
+unchanged. `payment refund recover` checks an existing local or external refund
+adjustment through its stored provider reference; it never creates a new refund:
+
+```sh
+rsvp payment refund recover \
+  --ack-sensitive-data --allow-external-write --allow-financial-write \
+  --allow-state-change --target adjustment_123 \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","paymentAttemptId":"attempt_123","adjustmentId":"adjustment_123"}'
+```
+
+The organization/event/attempt and adjustment must belong together, and the
+caller must retain payment-adjustment permission through the provider lookup;
+current actor authority and event lifecycle are rechecked transactionally before
+any financial or audit writes. Repeated checks reconcile the
+same adjustment safely; a missing provider reference requires separate operator
+reconciliation, not a new key or refund request.
+
+### Tax configuration and breakdowns
+
+`payment configure` accepts optional `tax` JSON. Use `{"mode":"NONE"}` for
+no tax. `INCLUSIVE` extracts tax from the configured price; `EXCLUSIVE` adds
+tax to it. Both taxable modes require a trimmed `label` (1–50 characters), an
+integer `rateBasisPoints` from 0 to 10000, and explicit `donationTaxable`.
+**100 basis points = 1%.** The example below is illustrative, not a recommended
+rate or a decision about whether donations are taxable.
+
+Read the current policy and `configurationVersion` before configuring, and
+replace the IDs, version, amounts and tax settings for the intended event:
+
+```sh
+rsvp payment event get --allow-financial-write \
+  --payload '{"organizationId":"org_123","eventId":"evt_123"}'
+
+rsvp payment configure \
+  --allow-external-write --allow-financial-write --allow-state-change \
+  --target evt_123 \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","eventVersion":7,"enabled":true,"currency":"SGD","amountMinor":1000,"pricingMode":"PER_REGISTRATION","donationMaximumMinor":500,"checkoutExpiryMinutes":30,"reservationPolicy":"HOLD_UNTIL_EXPIRY","tax":{"mode":"EXCLUSIVE","rateBasisPoints":900,"label":"Tax","donationTaxable":false}}'
+```
+
+This is a complete configuration write, not a tax-only patch: preserve the
+intended payment policy and credential selection. Add `flowId` for a named
+form override; `useEventDefaults: true` makes that form inherit the event policy,
+including tax. Omitted tax remains compatible with legacy no-tax configuration.
+Read `payment event get` back with the same scope to verify the saved policy.
+
+`payment mine get` exposes the attempt's saved tax quote and subtotal/tax/final
+total. `payment event list` exposes each attempt's original `quote` plus
+`refundBreakdown` (cumulative refunded subtotal, tax and total). Pending refunds
+are not confirmed refunded amounts. These are payment breakdowns, not statutory
+tax invoices. Organizers choose applicable settings; configuration does not
+establish legal approval or activate an event. Deploy matching API/web/CLI
+support before using these fields.
+
+### Pending Stripe connection preparation
+
+Organization managers can persist separate named Sandbox and Live connections
+without either secret. Generate one webhook UUID for each request, keep it for
+retries, and replace all illustrative IDs below:
+
+```sh
+rsvp stripe credential prepare \
+  --allow-external-write --allow-state-change --target org_123 \
+  --payload '{"organizationId":"org_123","name":"Client Sandbox","livemode":false,"webhookSourceId":"9dd0ba39-b55e-4e65-aa3e-d08242c45b8f"}'
+
+rsvp stripe credential preparation list \
+  --payload '{"organizationId":"org_123"}'
+```
+
+The response includes the saved preparation ID, webhook path, environment,
+endpoint API version and required events. Confirm the deployment/hosting origin
+before constructing the full client URL. Pending records survive reload but are
+not usable payment credentials or defaults and cannot verify webhooks. Pending
+names are also protected from legacy credential creation and rename operations;
+unreserved names remain supported.
+
+Prefer **Complete setup** in the encrypted integrations UI for secret entry.
+For approved private automation, `stripe credential complete` calls the same
+API with `organizationId`, the unchanged `name`, saved `preparationId` and
+`webhookSourceId`, plus `secretKey` and `webhookSecret`. It requires
+`--allow-external-write --allow-state-change --target <organizationId>`.
+Both restricted `rk_` and secret `sk_` server keys are supported. Never place
+secrets in chat, payment payloads, committed files, or shared shell history.
+The complete command returns only public credential metadata.
+
+Then `stripe credential test` takes `organizationId` and `credentialId` with
+`--allow-external-write --allow-state-change --target <credentialId>`.
+Its bounded account/Balance/Checkout/PaymentIntent/Refund reads verify the
+prepared mode and read access, not write permission or webhook delivery. Only a
+tested usable connection can be selected for payments; perform a separate sandbox
+payment and webhook acceptance check before launch. These commands use the
+normal authenticated API and never bypass organization-management permission.
+
+Deploy with the schema/client and webhook prerequisites in
+[the application guide](../../../apps/rsvp/README.md#refunds). Local generated
+clients can be refreshed with `bun db:generate`; that is not a database push or
+proof of deployed schema state.
+
+## Lucky Draw check-in cutoff
+
+The event manager can save an optional cutoff in **Check-in → Settings → Lucky
+draw eligibility**, in the event's configured timezone. The API stores an absolute
+ISO timestamp with an explicit offset (`Z` or `±HH:MM`), not a browser-local time.
+There is no fixed cutoff or 8 PM default. Unconfigured events return
+`luckyDrawEligibility.cutoffAt: null`; malformed stored values also return `null`
+rather than being interpreted in the browser's timezone.
+
+Read the event first:
+
+```sh
+rsvp event get --organization-id org_123 --event-id evt_123
+```
+
+Copy its current `configurationVersion` into the setup payload's `version`.
+Replace all example IDs, version `7`, and the illustrative timestamp below with
+values for the intended event; the date, time, and offset are not defaults:
+
+```sh
+rsvp event setup step update \
+  --allow-state-change \
+  --target evt_123 \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","version":7,"section":"LUCKY_DRAW","cutoffAt":"2030-06-15T13:30:00+02:00"}'
+```
+
+To clear the cutoff, read the event again and use its fresh version with
+`cutoffAt: null` (not a blank string):
+
+```sh
+rsvp event setup step update \
+  --allow-state-change \
+  --target evt_123 \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","version":7,"section":"LUCKY_DRAW","cutoffAt":null}'
+```
+
+Both writes require `event.manage`, the explicit state-change acknowledgement,
+and a `--target` matching the payload's `eventId`. A stale version returns
+`CONFLICT`: fetch the event, review the latest settings, then retry with its
+current version rather than replaying an old payload. Read the event back after
+a successful write to verify the cutoff and configuration version.
+
+This configuration step only stores the cutoff and preserves unrelated event
+metadata. It does not choose eligible people, apply category/exclusion rules,
+import a draw roster, or reconcile prizes/vouchers. Deploy the updated API before
+saving the new setup section; no database schema migration is required.
+
 ## Per-form confirmation presentation
 
 In the form builder's **Flow settings → Confirmation and check-in pass**, set
@@ -302,40 +529,24 @@ rsvp check-in by-reference \
 
 High-impact payment and retention commands remain protected by their matching financial, deletion, external-write, and sensitive-data gates. The API always re-evaluates the authenticated user's current Registration role, organization membership, event assignment, and resource permissions.
 
-## Operational report exports
-
-`export request` accepts `format: "XLSX"` (the default when omitted) or `"CSV"`.
-Use `filters.view` to name the population rather than relying on a dataset label:
-
-- RSVP: `MASTER` (all invitees, grouped employee/guest responses; default),
-  `CURRENT` (current response rows per person), `HISTORY` (all registration
-  records, not every edit revision), or `CLIENT_REGISTRATION` (current completed
-  employee/guest responses, including declines; excludes nonrespondents/drafts).
-  The client XLSX has **Attending**, **Not Attending**, **Master**, and **Metadata**
-  sheets; its CSV contains Master data only. Guest staff/department fields
-  describe the host, while menu and dietary answers remain person-scoped.
-- SEATING: `CURRENT` (active bookings; default) or `HISTORY` (active and released).
-- ATTENDANCE: `CURRENT` (expected people; default) or `CHECKED_IN` (expected people
-  with a check-in that has not been undone), or `ALL_INVITEES` (roster invitees,
-  including nonrespondents/declines, plus current guests). Registered, submitted,
-  attending, and active check-in states remain separate. None defines draw
-  eligibility.
+## Registration master list export
 
-Form, registration-status and submission-date filters apply only to RSVP.
-Other datasets do not accept `view`. These combinations are validated by the API.
+`export request` queues the single **Registration master list** Excel workbook
+(one **Master List** sheet; question columns follow the event's form). The
+payload is `organizationId`, `eventId` and an audit `reason`; the old `dataset`,
+`format` and `filters` fields are ignored. See the RSVP app README for columns.
 
 ```sh
 rsvp export request \
   --ack-sensitive-data \
   --allow-state-change \
   --target evt_123 \
-  --payload '{"organizationId":"org_123","eventId":"evt_123","dataset":"RSVP","format":"XLSX","filters":{"view":"MASTER"},"reason":"Organizer master list"}'
+  --payload '{"organizationId":"org_123","eventId":"evt_123","reason":"Organizer master list"}'
 ```
 
 Use `export list` to check the requester-scoped job, then `export download` for
-its current authorized download URL. For the client workbook, replace `MASTER`
-in the example with `CLIENT_REGISTRATION`. For the all-invitee attendance report,
-set `dataset` to `ATTENDANCE` and `filters.view` to `ALL_INVITEES`.
+its current authorized download URL. `event registrations export` and
+`event check-ins export` were removed; use `export request` instead.
 
 Operational check-in accepts `ATTENDING` and legacy `SUBMITTED`; roster/detail,
 manual/QR/reference entry, `report overview`, and `event people overview` use that same
@@ -343,9 +554,8 @@ population. Non-operational statuses remain excluded, and permissions, payment
 gates, duplicate protection, and undo behavior are unchanged. The web panel's
 realtime connection and manual refresh controls do not add a CLI subscription.
 
-Deploy matching API and export-worker versions before requesting the new views;
-old servers/workers do not understand them. Existing CLI commands pass the JSON
-payload to the shared typed API, so no new command or client-only rules are needed.
+Deploy matching API and export-worker versions together; an old worker would build the retired
+registration-records report for master-list jobs.
 
 ## Seating updates
 

package/dist/index.js

@@ -6326,7 +6326,7 @@ var commands = {
     effects: [],
     operation: (api, input) => api.eventFlow.preview.query(input),
     payloadOnly: true,
-    summary: "Validate and preview an event flow definition (--payload JSON)."
+    summary: "Validate and preview an event flow, including date-limit messages (--payload JSON)."
   },
   "event flow draft get": {
     effects: [],
@@ -6372,7 +6372,7 @@ var commands = {
     operation: (api, input) => api.eventFlow.saveDraft.mutate(input),
     payloadOnly: true,
     targetKey: "eventId",
-    summary: "Save a revision-checked registration flow draft (--payload JSON)."
+    summary: "Save a revision-checked draft; omitted admissionPolicy preserves roster-only access, explicit OPEN permits intentional broadening (--payload JSON)."
   },
   "event flow published get": {
     effects: [],
@@ -6549,7 +6549,7 @@ var commands = {
     effects: ["sensitive-data", "state-change"],
     operation: (api, input) => api.export.requestExport.mutate(input),
     payloadOnly: true,
-    summary: "Request an operational report (--payload JSON; format CSV/XLSX, default XLSX; RSVP views MASTER/CURRENT/HISTORY/CLIENT_REGISTRATION; ATTENDANCE views CURRENT/CHECKED_IN/ALL_INVITEES; SEATING views CURRENT/HISTORY)."
+    summary: "Request the registration master list XLSX (--payload JSON: eventId, organizationId, reason)."
   },
   "export list": {
     effects: ["sensitive-data"],
@@ -6613,8 +6613,8 @@ var eventScopeQueryCommand = (operation, summary) => ({
   summary
 });
 Object.assign(commands, {
-  "payment configure": payloadCommand((api, input) => api.payment.configureEventPayment.mutate(input), "Configure event payments (--payload JSON).", ["external-write", "financial-write", "state-change"]),
-  "payment checkout create": payloadCommand((api, input) => api.payment.createCheckout.mutate(input), "Create the caller's payment checkout (--payload JSON).", ["external-write", "financial-write", "state-change"]),
+  "payment configure": payloadCommand((api, input) => api.payment.configureEventPayment.mutate(input), "Configure event or form payments with optional tax: NONE, INCLUSIVE or EXCLUSIVE; taxable modes require label, rateBasisPoints (100 = 1%) and explicit donationTaxable (--payload JSON).", ["external-write", "financial-write", "state-change"]),
+  "payment checkout create": payloadCommand((api, input) => api.payment.createCheckout.mutate(input), "Create the caller's checkout; slow-settling payment methods are excluded (--payload JSON).", ["external-write", "financial-write", "state-change"]),
   "access mine": payloadCommand((api, input) => api.access.getMyEventAccess.query(input), "Get the caller's event access (--payload JSON)."),
   "access list": payloadCommand((api, input) => api.access.listEventAccess.query(input), "List event access grants (--payload JSON).", ["sensitive-data"]),
   "access assignment list": payloadCommand((api, input) => api.access.listEventAssignments.query(input), "List event assignments (--payload JSON)."),
@@ -6647,8 +6647,6 @@ Object.assign(commands, {
   "event seating seat tier update": payloadCommand((api, input) => api.event.setSeatAudienceTier.mutate(input), "Set or inherit an audience tier for seating seats (--payload JSON).", ["state-change"], "eventId"),
   "event field deactivate": payloadCommand((api, input) => api.event.deactivateFieldDefinition.mutate(input), "Deactivate an event field (--payload JSON).", ["delete", "state-change"]),
   "event field upsert": payloadCommand((api, input) => api.event.upsertFieldDefinition.mutate(input), "Create or update an event field (--payload JSON).", ["sensitive-data", "state-change"]),
-  "event check-ins export": payloadCommand((api, input) => api.event.exportCheckIns.mutate(input), "Export check-ins (--payload JSON).", ["sensitive-data", "state-change"]),
-  "event registrations export": payloadCommand((api, input) => api.event.exportRegistrations.mutate(input), "Export registrations (--payload JSON).", ["sensitive-data", "state-change"]),
   "event rsvp mine": payloadCommand((api, input) => api.event.getMyRsvp.query(input), "Get the caller's registration (--payload JSON).", ["sensitive-data"]),
   "event people overview": payloadCommand((api, input) => api.event.getPeopleOverview.query(input), "Get people operations overview (--payload JSON).", ["sensitive-data"]),
   "event reminder counts": payloadCommand((api, input) => api.event.getReminderSegmentCounts.query(input), "Get reminder segment counts (--payload JSON).", ["sensitive-data"]),
@@ -6682,12 +6680,17 @@ Object.assign(commands, {
 });
 Object.assign(commands, {
   "payment event get": payloadCommand((api, input) => api.payment.getEventPayment.query(input), "Get event payment configuration (--payload JSON).", ["financial-write"]),
-  "payment mine get": payloadCommand((api, input) => api.payment.getMyPayment.query(input), "Get the caller's payment (--payload JSON).", ["financial-write", "sensitive-data"]),
-  "payment event list": payloadCommand((api, input) => api.payment.listEventPayments.query(input), "List event payments (--payload JSON).", ["financial-write", "sensitive-data"]),
+  "payment mine get": payloadCommand((api, input) => api.payment.getMyPayment.query(input), "Get the caller's payment with its saved subtotal, tax and final total breakdown (--payload JSON).", ["financial-write", "sensitive-data"]),
+  "payment event list": payloadCommand((api, input) => api.payment.listEventPayments.query(input), "List event payments with original quote and cumulative refunded subtotal/tax/total, including verified external refunds (--payload JSON).", ["financial-write", "sensitive-data"]),
   "payment exception list": payloadCommand((api, input) => api.payment.listPaymentExceptions.query(input), "List payment exceptions (--payload JSON).", ["financial-write", "sensitive-data"]),
   "payment exception resolve": payloadCommand((api, input) => api.payment.resolvePaymentException.mutate(input), "Resolve a payment exception (--payload JSON).", ["financial-write", "sensitive-data", "state-change"]),
   "payment reconcile": payloadCommand((api, input) => api.payment.reconcilePayment.query(input), "Compare a payment attempt with its provider (--payload JSON).", ["external-write", "financial-write"]),
   "payment refund": payloadCommand((api, input) => api.payment.refundPayment.mutate(input), "Refund a payment (--payload JSON).", ["external-write", "financial-write", "state-change"]),
+  "stripe credential prepare": payloadCommand((api, input) => api.organization.prepareStripeCredential.mutate(input), "Persist a named pending Sandbox/Live Stripe connection and stable webhook URL without secrets (--payload JSON).", ["external-write", "state-change"], "organizationId"),
+  "stripe credential complete": payloadCommand((api, input) => api.organization.createStripeCredential.mutate(input), "Complete a saved Stripe preparation using its exact IDs/name and private credentials (--payload JSON); secrets remain write-only.", ["external-write", "state-change"], "organizationId"),
+  "stripe credential test": payloadCommand((api, input) => api.organization.testStripeCredential.mutate(input), "Run bounded account/Balance/Checkout/PaymentIntent/Refund read checks for a saved connection (--payload JSON).", ["external-write", "state-change"], "credentialId"),
+  "stripe credential preparation list": payloadCommand((api, input) => api.organization.listStripeCredentialPreparations.query(input), "List organization-scoped pending Stripe connections and webhook setup instructions (--payload JSON)."),
+  "payment refund recover": payloadCommand((api, input) => api.payment.recoverRefund.mutate(input), "Check an existing scoped refund adjustment without creating a provider refund (--payload JSON).", ["external-write", "financial-write", "state-change"], "adjustmentId"),
   "retention overview": payloadCommand((api, input) => api.retention.getRetentionOverview.query(input), "Get retention overview (--payload JSON).", ["sensitive-data"]),
   "retention hold create": payloadCommand((api, input) => api.retention.createLegalHold.mutate(input), "Create a legal hold (--payload JSON).", ["sensitive-data", "state-change"]),
   "retention hold release": payloadCommand((api, input) => api.retention.releaseLegalHold.mutate(input), "Release a legal hold (--payload JSON).", ["delete", "sensitive-data", "state-change"]),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@go-labs-sg/rsvp",
-  "version": "0.17.0",
+  "version": "1.0.0",
   "description": "RSVP CLI for authorized event operations.",
   "type": "module",
   "main": "./dist/index.js",