Sync latest source into cli master

docs/commands.md

@@ -25,6 +25,7 @@ This package has **zero** `@dealmachine/*` dependencies -- it is a self-containe
   - [Comps](#comps-commands) -- comparable property analysis
   - [Lists](#lists-commands) -- `search`, `create`, `get`, `update`, `delete`, `build`, `import`, `items`, `add`, `remove`, `export`
   - [Driving](#driving-commands) -- `list`, `get`
+  - [Mail campaigns](#mail-campaign-commands) -- `list`, `create`, `get`, `add-properties`, `estimate-add`, `pause`, `resume`, `end`
   - [Filters](#filters-commands) -- list available search filters
   - [Fields](#fields-commands) -- list available data fields
   - [Activity](#activity-commands) -- `search`, `get`
@@ -861,6 +862,34 @@ dm prospects list --source driving
 
 Drive history is read-only. Use `dm prospects` for lifecycle, notes, and tags on linked Prospects.
 
+### Mail Campaign Commands
+
+A mail campaign is a sequence of mail steps. Campaigns built in the app's campaign creator, campaigns saved as Ready, and campaigns created with `"accepts_properties": true` keep accepting properties while they are Ready, Active or Paused. Other campaigns created with an audience work as before and end when their mail is done. Each added property starts at step 1 on its own schedule; properties already in the campaign are not changed.
+
+Statuses are `draft`, `ready`, `active`, `paused` and `ended`. Ready means nothing is queued to mail. Completed and Cancelled campaigns from before this change show as `ended`; `--status completed` and `--status cancelled` still work as filters.
+
+```bash
+dm mail campaigns list --accepting-properties          # Campaigns you can add properties to now
+dm mail campaigns list --status ended --json
+dm mail campaigns create --body '{"name":"Seller follow-up","steps":[{"design_id":"des_123"}]}'   # No audience: saved as Ready, no charge
+dm mail campaigns estimate-add camp_abc123 --count 25
+dm mail campaigns add-properties camp_abc123 --property-ids 101 102 --recipient owner
+dm mail campaigns add-properties camp_abc123 --property-ids 101,102 --recipient resident --yes --json
+dm mail campaigns pause camp_abc123
+dm mail campaigns end camp_abc123
+```
+
+| Command | What it does |
+| --- | --- |
+| `add-properties <id> --property-ids <ids...> --recipient owner\|resident` | Shows the charge due today and later, asks for confirmation, then adds up to 5,000 properties. Prints the added count and each skipped property with its reason (already in the campaign, Do Not Contact, no mailing address, duplicate mailing address, archived prospect, not found). |
+| `estimate-add <id> --count <n>` | Shows what adding `n` properties costs: charged today, charged later, pieces per property and whether your wallet covers it. For a paused campaign nothing is charged today; each piece is charged as it goes out after you resume it. Nothing is added. |
+| `end <id>` | Ends the campaign permanently after a confirmation. Unsent mail stops; the campaign cannot be paused, resumed or added to. Mail already printed still delivers. |
+| `list --accepting-properties` | Lists only campaigns that properties can be added to now. |
+
+`--recipient owner` mails the owner's mailing address; `--recipient resident` mails the current resident at the property address. Pieces going out today are charged when added; later pieces are charged as they go out. Auto-reload must be on when the campaign has more than one step, a step that repeats, or any delay.
+
+`add-properties` and `end` need `--yes` when run by an agent, a script, with `--json`, or without a terminal. Without it, `add-properties` prints the estimate (with `"confirmation_required": true` in `--json` output), adds nothing and exits with code 1; `end` stops with an error and exits with code 1. `end` refuses a draft, which has not started; cancel a draft with `delete <id>`. `delete <id>` cancels a campaign without a confirmation, gives the same result as `end` for a started campaign, and succeeds without changes for a campaign that has already ended.
+
 ### Filters Commands
 
 #### `dm filters`

npm-alias/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dealmachine",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Short install alias for the DealMachine property intelligence CLI",
   "author": "DealMachine",
   "license": "MIT",
@@ -23,7 +23,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@dealmachine/cli": "0.4.1"
+    "@dealmachine/cli": "0.5.0"
   },
   "engines": {
     "node": ">=18"

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dealmachine/cli",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "DealMachine CLI for property intelligence, people lookup, and enrichment through the public API",
   "author": "DealMachine",
   "license": "MIT",

playbook/PLAYBOOK.md

@@ -695,6 +695,22 @@ dm lists export <list_id> --anchor person
 dm lists export <list_id> --fields estimated_value,owner_full_name --anchor property
 ```
 
+### Mail Campaigns (adding properties costs mail credits)
+
+```bash
+dm mail campaigns list --accepting-properties --json      # Campaigns that can take properties now
+dm mail campaigns estimate-add <id> --count 25 --json     # Charge due today and later (FREE)
+dm mail campaigns add-properties <id> --property-ids 101 102 --recipient owner --yes --json
+dm mail campaigns end <id> --yes                          # Permanent
+```
+
+- Statuses: `draft`, `ready`, `active`, `paused`, `ended`. Completed and Cancelled show as `ended`.
+- Ask the user owner or resident before adding. Each added property starts at step 1.
+- Always run `estimate-add` first and tell the user the charge due today (`pay_today_cents`) and later. Pass `--yes` only after they approve. Without `--yes`, `add-properties` returns the estimate, adds nothing and exits with code 1. For a paused campaign nothing is charged today; pieces are charged as they go out after it resumes.
+- Report `added_count` and every skipped property with its reason.
+- Ending is permanent: unsent mail stops and the campaign can never be resumed or added to. Confirm with the user before `end --yes`.
+- Create a campaign with no audience to save it as Ready with no charge, then add properties later. To add properties later to a campaign created with an audience, include `"accepts_properties": true` when you create it.
+
 ### Activity (FREE)
 
 ```bash