frontpage-host 0.2.3 → 0.2.4

package/AGENTS.md

@@ -267,3 +267,5 @@ Payments, invoices and recurring billing: see packaged [PAYMENTS.md](./PAYMENTS.
 
 
 Offerings own every standalone Pay now payment. Use `frontpage payments buttons list|get|create|update|archive|restore`; create the saved offering before adding its returned `data-fp-pay` markup. Supports `--receipt-template-id UUID`, `--default-receipt`, `--active true|false`, combined price/details updates and JSON payloads. Archive deletes from active checkout but preserves history. The website agent uses the same service automatically for ordinary payment-button requests. Store stays cart-only; invoices stay saved customer-addressed records. Full instructions: PAYMENTS.md and https://frontpage.host/developers/payments.
+
+Currency is owned by Payments and read by Store, Offerings and invoices. Offering create/get/update responses include exact receiptVariables. For custom confirmations, declare those names with existing mail template commands, attach receiptTemplateId, and verify both records. Only include expressly selected answers; keep private answers excluded. Forms still use input-name tokens and confirmTemplateId.

package/PAYMENTS.md

@@ -409,3 +409,61 @@ not automatically join its submission to a payment.
 Offerings work without Store markup. The platform supplies a Payments drawer for buyer-chosen amounts and saved questions; fixed payments without questions proceed to Stripe Checkout. Never add a Cart button or Store drawer for an Offering.
 
 For custom appearance, include one shared `<template data-fp-payment-drawer>` using the required panel, title, close, amount, fields, error and confirm hooks documented by the Payments agent module. Style it with normal site CSS and payment-specific variables. Keep dynamic questions in the saved Offering, not in page HTML. UI, CLI and agent question edits appear on the next opening without republishing. Template/style edits use normal website publishing. Payments never changes the Store cart or its saved delivery choices.
+
+
+## Currency and confirmation answer variables
+
+Payments owns the site's currency from the existing Stripe connection process.
+Store, Offerings, invoices, checkout and public price display read the same saved
+Payments currency. It is read-only; do not set a Store currency or guess USD when
+setup is pending. Recorded transactions retain the currency actually charged.
+
+Offering create/get/update responses include `receiptVariables`, an array of
+`{name,label}`. The standard receipt variables are `buyer_name`, `buyer_email`,
+`total`, `currency`, and `items`. An included question also exposes
+`answer_<customizationId>`. For example, the saved field ID `appointment-date`
+provides `{{answer_appointment-date}}` when `includeInReceipt:true`.
+Read returned names rather than constructing names from editable labels.
+
+Use the existing template commands:
+
+```bash
+frontpage payments buttons get consultation --site YOUR_SITE --json
+frontpage mail template create --file confirmation.json --site YOUR_SITE --json
+frontpage payments buttons update consultation --receipt-template-id TEMPLATE_UUID --site YOUR_SITE --json
+frontpage mail template get TEMPLATE_UUID --site YOUR_SITE --json
+```
+
+A template document declares the tokens it uses:
+
+```json
+{
+  "name": "Consultation confirmation",
+  "subject": "Thank you, {{buyer_name}}",
+  "preheader": "Your consultation payment confirmation",
+  "variables": ["buyer_name", "answer_appointment-date", "total"],
+  "blocks": [
+    {"type":"paragraph","text":"Requested date: {{answer_appointment-date}}"},
+    {"type":"paragraph","text":"Total paid: {{total}}"}
+  ]
+}
+```
+
+Only answers explicitly included in the receipt are available. Private answers
+stay in authorized payment details. Existing `{{items}}` summaries still work.
+Stable IDs keep tokens working after a label edit. Historical receipts use the
+captured answers, not today's question definitions. An optional unanswered field
+can be blank; zero and false are values. Unavailable variables or a wrong-site
+template receive a validation error. Correct a shared template before removing
+its required field, or detach/replace it in the same Offering update.
+
+Forms keep their existing convention: `{{company_name}}` reads the submitted
+input named `company_name`, and the form uses `confirmTemplateId`. Offerings use
+`receiptTemplateId`. Store buyer receipts keep their five standard variables.
+There is no separate mapping interface or variable picker.
+
+Activity includes `metrics` for the last 30 days: gross received money, successful
+payment count, and average payment, grouped by currency. Gross is before fees and
+refunds. Schedules are not received money. Metrics cover the full recorded period,
+not only the capped Activity rows. Dates use verified successful-payment times;
+older records without proof show that the date is unavailable.

package/README.md

@@ -66,3 +66,5 @@ Payments, invoices and recurring billing: see packaged [PAYMENTS.md](./PAYMENTS.
 
 
 Offerings own every standalone Pay now payment. Use `frontpage payments buttons list|get|create|update|archive|restore`; create the saved offering before adding its returned `data-fp-pay` markup. Supports `--receipt-template-id UUID`, `--default-receipt`, `--active true|false`, combined price/details updates and JSON payloads. Archive deletes from active checkout but preserves history. The website agent uses the same service automatically for ordinary payment-button requests. Store stays cart-only; invoices stay saved customer-addressed records. Full instructions: PAYMENTS.md and https://frontpage.host/developers/payments.
+
+Payments owns the shared currency from Stripe setup; Store reads it. Offering create/get/update JSON returns `receiptVariables` for custom confirmation templates, including eligible `answer_<customizationId>` tokens. Use existing mail template commands and attach with `--receipt-template-id`; see PAYMENTS.md.

package/dist/registry.js

@@ -518,7 +518,7 @@ export const COMMANDS = [
         flags: [
             "items list|get|create|update|archive|restore|activate|images|stock; use --file for nested variants, options, customizations and images. Existing fixed/open pricing is retained. Store always uses Add to cart.",
             "Descriptions use a small markdown subset. Bind data-fp-store-bind=description for the full product story; do not bake titles, prices or images into the page. Store is cart-only; use Payments for explicit Pay now.",
-            "items stock uses --add/--remove as a signed delta, or --set/--unlimited. Never combine these verbs. Product pages use data-fp-store-product and the platform cart templates. Store prices use the account currency.",
+            "items stock uses --add/--remove as a signed delta, or --set/--unlimited. Never combine these verbs. Product pages use data-fp-store-product and the platform cart templates. Store prices read the shared currency owned by Payments.",
             "variants add|update|archive|restore; categories list|create|rename|archive. Create categories before assigning their slugs.",
             "settings get|set-fulfillment|set-checkout-fee|set-receipt|availability get|on|off. Fee mode flat uses --cents; percent uses --bps (250 is 2.5%). Receipt takes --template <id> or --stock. Availability requires admin and --yes in scripts.",
             "orders list|get; import explicitly reads the existing site product files. No fleet import or data conversion occurs.",
@@ -548,6 +548,7 @@ export const COMMANDS = [
             "availability preview|on|off. off reads affected counts before confirmed pause/void; a partial response stays off and requires another off request. on never resumes stopped billing or restores void invoices.",
             "activity list|get <id> --source order|payment. invoices and recurring have separate get commands. Source IDs never collide.",
             "buttons list [--limit 1..100 --offset N --archived true]; get|create|update|archive|restore. These manage Offerings. Create uses --id, --title, --price-cents, optional --amount open --min-cents. Create/update support --description, --active true|false, --receipt-template-id UUID or --default-receipt, and --file. Price, details and template save together. Archive deletes from new payments while retaining history; archive/restore require --yes. Only registered Offerings authorize Pay now; page markup and Store flags never do.",
+            "Offering create/get/update JSON includes receiptVariables. Use exact names in existing mail templates, then attach --receipt-template-id. Included answers expose answer_<customizationId>; private answers are excluded. Currency is owned by Payments, not Store.",
             "tax get; tax settings --file <file> --yes; tax registrations list|add --country US --state CA --yes|end <id> --yes. Supply the business's actual tax registrations. No automatic tax advice or raw Account Session secrets.",
             "invoices preview|send --file <file>; list [--limit 1..100 --offset N --arrangement <id>]; get|refresh|resend|void <id>. send/resend need --operation-key; send needs --preview-hash; financial writes require --yes in scripts.",
             "recurring preview|create --file <file>; list|get|refresh|cancel|resume|resend-invitation. Supported cadence: weekly, fortnightly, monthly, quarterly, yearly; firstDate YYYY-MM-DD, explicit IANA timeZone, 09:00 start. create/resume/invitation need stable operation keys. Resume requires first-date, preview-hash and --yes; no missed-period backfill.",

package/llms.txt

@@ -43,3 +43,5 @@ Payments, invoices and recurring billing: see packaged [PAYMENTS.md](./PAYMENTS.
 
 
 Offerings own every standalone Pay now payment. Use `frontpage payments buttons list|get|create|update|archive|restore`; create the saved offering before adding its returned `data-fp-pay` markup. Supports `--receipt-template-id UUID`, `--default-receipt`, `--active true|false`, combined price/details updates and JSON payloads. Archive deletes from active checkout but preserves history. The website agent uses the same service automatically for ordinary payment-button requests. Store stays cart-only; invoices stay saved customer-addressed records. Full instructions: PAYMENTS.md and https://frontpage.host/developers/payments.
+
+Payments owns Stripe currency. Read Offering receiptVariables before creating a confirmation template; attach it through Payments. Forms use submitted input names. Full receipt contract: PAYMENTS.md.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontpage-host",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Frontpage CLI — manage your site from the terminal",
   "type": "module",
   "bin": {