frontpage-host 0.1.26 → 0.1.28

package/PEOPLE.md

@@ -102,11 +102,12 @@ frontpage people groups create --file repeat-buyers.json --site YOUR_SITE --json
 frontpage people membership override --person PERSON_ID --group GROUP_ID --override include --site YOUR_SITE --json
 frontpage people membership override --person PERSON_ID --group GROUP_ID --override exclude --site YOUR_SITE --json
 frontpage people membership override --person PERSON_ID --group GROUP_ID --override auto --site YOUR_SITE --json
-frontpage people membership hold --person PERSON_ID --group GROUP_ID --hold true --site YOUR_SITE --json
 frontpage people membership hold --person PERSON_ID --group GROUP_ID --hold false --site YOUR_SITE --json
 ```
 
-`include` keeps one person in an automatic group; `exclude` keeps them out. `auto` clears the exception. A hold pauses automatic changes and that group’s attached email for this person. It does not prevent an owner from making an explicit change.
+`include` keeps one person in an automatic group; `exclude` keeps them out. `auto` clears the exception and applies that group’s conditions immediately when the needed facts are available. It can add or remove membership and run the group’s normal rules. It does not change other groups or email permission. An earlier saved pause still prevents automatic changes.
+
+**Earlier pauses.** New `--hold true` requests fail unless the person already has that pause; an existing pause remains unchanged. Use `--hold false` to resume a saved pause. This keeps membership, stage and exception, restarts the time-rule clock, and skips earlier pending work for this person/group. It fails with HTTP 409 while a group rule is running; try again after it finishes. Archived groups must be restored first. No saved pause is cleared automatically. Failed runs remain available for an explicit review and retry; resuming does not retry them.
 
 **Preserve existing records.**
 
@@ -337,18 +338,78 @@ Copy the attachment’s returned rule ID before enabling it. Pass `--enabled fal
 
 See the [Email guide](/developers/mail) for content blocks, template variables, series step delays, sender settings, and email limits.
 
-## Email permission is independent of groups
+## Marketing email permission
+
+Permission belongs to the email address and site. Groups and stages never grant it. A person who opts out stays in their groups and stages. Campaign selection, rules, direct-address sends, series and delivery enforce saved withdrawals and restrictions.
+
+### Defaults and explicit choices
+
+| Entry point | New contact | Existing contact |
+| --- | --- | --- |
+| Owner UI, `people add`, public API `POST /people`, agent `add_person` | `allowed` by default, recorded as an owner assertion | Omitted choice preserves the saved decision. Explicit choices can fill unknown permission; add cannot reverse a recorded refusal, mailing-list unsubscribe or suppression. |
+| CSV import | Unknown unless an explicit list-wide choice or row value supplies permission | List-wide choices leave existing decisions alone. Row values can record permission, but cannot reverse a refusal, unsubscribe or suppression. |
+| Forms, orders, bookings and account events | Unknown unless a supported subscriber signup records agreement | Preserve saved permission; purchases and signup timestamps are not email agreement. |
+| Group, stage, name, phone, note and follow-up changes | No permission change | No permission change. Changing an email does not transfer an old address's grant; a recorded refusal stays in effect. |
 
-Group membership never grants email permission. A person who opts out stays in their groups and stages, while automated marketing emails and campaigns stop. Every delivery checks permission again, so an unsubscribe after audience selection still stops delivery.
+The add choice is `allowed`, `unknown`, or `not_allowed`. API and agent callers use the same `emailPermission` string field. CLI callers use `--email-permission`. Recording `allowed` asserts that you have permission; it does not obtain permission from the person.
 
 ```
-frontpage people person permission --person PERSON_ID --allowed false --site YOUR_SITE --json
+# New owner-added contacts default to permission given. Repeated adds preserve decisions.
+frontpage people add --email alex@example.com --site YOUR_SITE --json
+# Choose unknown when you do not have a recorded agreement:
+frontpage people add --email pat@example.com --email-permission unknown --site YOUR_SITE --json
+# Record refusal without enabling marketing:
+frontpage people add --email sam@example.com --email-permission not_allowed --site YOUR_SITE --json
 frontpage people membership get --person PERSON_ID --site YOUR_SITE --json
-# Only record permission when the person has actually given it:
+# Explicitly stop or record a new owner decision on the person:
+frontpage people person permission --person PERSON_ID --allowed false --site YOUR_SITE --json
 frontpage people person permission --person PERSON_ID --allowed true --site YOUR_SITE --json
 ```
 
-`membership.get` includes email eligibility and the reason a contact cannot receive mail. Missing email, hidden state, missing permission, saved unsubscribe, and suppression can block delivery. An owner can record a new permission decision, but cannot reverse a mailing-list unsubscribe or suppression. CSV values cannot reverse an existing opt-out, including a recorded false decision. Do not add a permission check to every group or stage; delivery already enforces it.
+`membership.get` reports eligibility and the reason mail cannot send. A missing/invalid email, hidden person, missing permission, recorded refusal, subscriber unsubscribe or suppression can block marketing. An active subscriber agreement can establish permission even without a separate CRM flag. A requested test copy can go to its test recipient without a recorded grant or a new subscription. Saved withdrawals, hidden state and suppression still apply. Transactional confirmations keep their own existing sending flow.
+
+An explicit address outside People is an owner-asserted recipient and does not create a CRM permission record. If that address matches a saved person, the normal CRM eligibility check applies. Known subscribers' unsubscribe and saved suppressions also apply when no CRM person matches. Once queued, a known person's ID stays attached so a later address change, hide or withdrawal prevents delivery. A test is not a way to send a customer campaign.
+
+New CRM decisions store state, exact email, source, actor and recording time in `attrs.emailPermissionRecord`; the boolean `attrs.emailPermission` stays compatible with existing callers. Historical grants without that record remain supported. Permission events preserve the decision history. Do not add a permission condition to every rule; the sender already checks it.
+
+### Repair reviewed historical permission without running rules
+
+Review each person's current address, agreement evidence, saved withdrawals and restrictions first. This operation only fills missing permission. It never adds a person, changes their groups/stages, clears a restriction, or replays automation.
+
+Save `repair.json` with real values:
+
+```json
+{
+  "personId": "PERSON_ID",
+  "allowed": true,
+  "backfill": true,
+  "expectedEmail": "alex@example.com",
+  "evidence": "Owner confirmed this person's marketing-email agreement on 2026-10-12",
+  "requestKey": "UNIQUE_REPAIR_UUID"
+}
+```
+
+```
+frontpage people person permission --file repair.json --site YOUR_SITE --json
+frontpage people membership get --person PERSON_ID --site YOUR_SITE --json
+```
+
+Reuse the same key and evidence after a lost response. A repeat returns `duplicate:true` without changing the decision again. If the person withdrew permission afterward, a retry does not restore it. A changed address, hidden person, existing decision, active subscriber agreement, unsubscribe or suppression refuses a new backfill. A new explicit owner decision uses the normal `allowed` operation instead; it still cannot reverse a subscriber unsubscribe or suppression.
+
+For a reviewed cohort, submit at most 25 people in each bounded batch. Each row needs its own stable request key:
+
+```json
+{
+  "allowed": true,
+  "backfill": true,
+  "evidence": "Owner confirmed marketing-email permission for this reviewed cohort",
+  "people": [
+    { "personId": "PERSON_ID", "expectedEmail": "alex@example.com", "requestKey": "UNIQUE_REPAIR_UUID" }
+  ]
+}
+```
+
+Run the same `person permission --file reviewed-batch.json` command. Read every row in `results`: domain conflicts include `error` and `status`, while successful rows include `emailPermission` and `duplicate`. The batch can partly succeed; receipts make a retry safe. Malformed batch input fails before any permission writes. Infrastructure errors can leave completed receipts, so retry the exact batch rather than inventing new keys. This capability works through the public API and `manage_people` too; it has no company-only endpoint.
 
 ## Import a customer list from CSV
 
@@ -363,7 +424,7 @@ Alex Rivera,alex@example.com,,
 Phone customer,,+12025550199,
 ```
 
-Map exact header names in `mapping.json`. The permission column is optional; omit it when permission is unknown. `yes`/`true` records existing permission and `no`/`false` records no permission.
+Map exact header names in `mapping.json`. The permission column is optional. `yes`/`true` records an owner assertion and `no`/`false` records refusal. A supplied row value takes priority over the list-wide choice; duplicate rows keep a negative decision. Set top-level `emailPermission` to `allowed`, `unknown`, or `not_allowed` for new people whose row has no permission value. Omission defaults to unknown. List-wide choices never change existing decisions. Imports preserve saved refusals, unsubscribe and suppression. Changing the list choice requires a new request key.
 
 ```
 {
@@ -375,7 +436,8 @@ Map exact header names in `mapping.json`. The permission column is optional; omi
   },
   "groupIds": [
     "GROUP_ID"
-  ]
+  ],
+  "emailPermission": "unknown"
 }
 ```
 
@@ -528,12 +590,12 @@ The agent can create and edit saved templates and series with the existing Email
 | stages.reorder                             | groupId, stageIds                                                   | Save every active stage ID in order, once each.                                          |
 | stages.archive / stages.restore            | id, groupId                                                         | Keep assignments and history while archiving or restoring.                               |
 | membership.get                             | personId                                                            | Memberships and email eligibility.                                                       |
-| membership.add / membership.remove         | personId, groupId; reset? on add                                    | Join or leave a manual group.                                                            |
+| membership.add / membership.remove         | personId, groupId; reset? on add                                    | Join or leave a group; a conditions group stores an include or exclude exception.                                                            |
 | membership.move                            | personId, fromGroupId, groupId, reset?                              | Leave one manual group and join another.                                                 |
 | membership.stage                           | personId, groupId, stageId                                          | Set a stage; null clears it without leaving the group.                                   |
 | membership.advance                         | personId, groupId                                                   | Move to the next nonterminal stage.                                                      |
 | membership.override                        | personId, groupId, override                                         | Use include, exclude, or null for automatic membership.                                  |
-| membership.hold                            | personId, groupId, hold                                             | Pause or resume automatic changes for this person/group.                                 |
+| membership.hold                            | personId, groupId, hold                                             | Resume an earlier saved pause; creating a new pause is no longer supported.                                 |
 | rules.list                                 | archived?                                                           | List rules; archived:true includes archived rules.                                       |
 | rules.get                                  | id                                                                  | Read the saved rule and version.                                                         |
 | rules.create                               | name, trigger, conditions?, actions, enabled?                       | Create a rule. Pass enabled:false to review it first.                                    |
@@ -544,7 +606,7 @@ The agent can create and edit saved templates and series with the existing Email
 | rules.runs                                 | ruleId?, cursor?, limit?                                            | Inspect saved outcomes and failed actions.                                               |
 | rules.retry                                | runId or ruleId                                                     | Retry eligible failed work; completed action receipts stay saved.                        |
 | attachments.create                         | groupId, stageId?, emailKind, emailId, enabled?, name?, conditions? | Create an ordinary group/stage entry rule for a template or series.                      |
-| person.permission                          | personId, allowed                                                   | Record an email-permission decision; mailing-list unsubscribe and suppression still win. |
+| person.permission | personId, allowed; backfill?, expectedEmail?, evidence?, requestKey?; or backfill batch with people (1–25) | Record a decision or repair reviewed missing permission without automation. Unsubscribe and suppression still win. |
 | audience.preview                           | audience                                                            | Preview matched and eligible People for a campaign.                                      |
 | import.preview                             | csv, mapping?, headersOnly?                                         | Validate a CSV and match existing contacts; sends nothing.                               |
 | import.start                               | csv, mapping?, groupIds?, requestKey                                | Start a saved import.                                                                    |

package/dist/commands/people.js

@@ -161,6 +161,9 @@ export async function runPeople(args) {
             const phone = takeFlag(work, "--phone");
             const name = takeFlag(work, "--name");
             const note = takeFlag(work, "--note");
+            const emailPermission = takeFlag(work, "--email-permission");
+            if (emailPermission !== undefined && !["allowed", "unknown", "not_allowed"].includes(emailPermission))
+                throw new CliHttpError("--email-permission is allowed, unknown, or not_allowed.", EXIT_USAGE, 0, "bad_request");
             assertNoUnknownFlags(work, "people");
             if (!email && !phone) {
                 console.error("Usage: frontpage people add --email you@example.com | --phone +15551234567 [--name …] [--note …]");
@@ -171,6 +174,7 @@ export async function runPeople(args) {
                 phone,
                 name,
                 note,
+                ...(emailPermission !== undefined ? { emailPermission } : {}),
             });
             if (isJson()) {
                 emitOk("people", data);

package/dist/registry.js

@@ -466,7 +466,7 @@ export const COMMANDS = [
             "CSV: --csv PATH plus --file mapping.json. import start requires a stable --request-key. Retry the same import with the same key and contents.",
             "list/export: --group GROUP_ID --stage STAGE_ID. See package PEOPLE.md for full examples and every JSON shape.",
             "list: --q --status --source --form-slug --follow-up due|upcoming|none --hidden --sort --last-seen-days --tag --limit --cursor",
-            "add requires --email and/or --phone (never name alone)",
+            "add requires --email and/or --phone (never name alone). New contacts default to owner-asserted email permission; --email-permission allowed|unknown|not_allowed changes this choice. Existing default decisions stay saved; withdrawals/restrictions cannot be overridden by add.",
             "tag: --add <label> | --remove <slug>",
             "export writes UTF-8 CSV (same filters as list). Optional --out <file>",
             "Hide is not forget. Unique email/phone stay; later ingest un-hides",

package/package.json

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