DEA-2166: prospect attribution filters on dm prospects list

docs/commands.md

@@ -862,10 +862,23 @@ dm driving list
 dm driving list --mode free_drive --started-after 2026-08-01 --json
 dm driving get drive_session_501
 dm prospects list --source driving
+dm prospects list --source-group d4d --added-by 7 --added-after 2026-10-01
 ```
 
 Drive history is read-only. Use `dm prospects` for lifecycle, notes, and tags on linked Prospects.
 
+`dm prospects list` also filters by how and when a Prospect was added:
+
+| Option | Description |
+| --- | --- |
+| `--source-group <group>` | `d4d` (added while driving) or `map` (added any other way) |
+| `--added-by <ids>` | Comma-separated user IDs who added the Prospect, e.g. `7,12` |
+| `--added-after <date>` | Added on or after this ISO date or date-time. A date means midnight UTC |
+| `--added-before <date>` | Added before this ISO date or date-time (not inclusive) |
+| `--status <statuses>` | Comma-separated: `hot`, `warm`, `cold`, `follow_up`, `do_not_contact`, `none` |
+
+Property and person records from `dm properties` and `dm people` include `is_prospect`, `prospect_source`, `prospect_added_by` and `prospect_added_at`.
+
 ### 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.

src/commands/prospects.ts

@@ -99,6 +99,11 @@ export async function prospectsList(options: {
   recordType?: string;
   lifecycle?: string;
   source?: string;
+  sourceGroup?: string;
+  addedBy?: string;
+  addedAfter?: string;
+  addedBefore?: string;
+  status?: string;
   favorites?: boolean;
   list?: string;
   tag?: string;
@@ -114,6 +119,11 @@ export async function prospectsList(options: {
       record_type: options.recordType,
       lifecycle: options.lifecycle,
       source: options.source,
+      source_group: options.sourceGroup,
+      added_by: options.addedBy,
+      added_after: options.addedAfter,
+      added_before: options.addedBefore,
+      status: options.status,
       favorites_only: options.favorites ? 'true' : undefined,
       list_id: options.list,
       tag_id: options.tag,

src/index.ts

@@ -1644,6 +1644,11 @@ prospectsCmd
   .option('--record-type <type>', 'property (default) or person')
   .option('--lifecycle <lifecycle>', 'active (default), opportunity, or archived')
   .option('--source <source>', 'Filter by source, e.g. driving, import, api, cli, or mcp')
+  .option('--source-group <group>', 'd4d (added while driving) or map (added any other way)')
+  .option('--added-by <ids>', 'Comma-separated user IDs who added the prospect, e.g. 7,12')
+  .option('--added-after <date>', 'Added on or after this date or ISO date-time (dates are UTC)')
+  .option('--added-before <date>', 'Added before this date or ISO date-time (dates are UTC)')
+  .option('--status <statuses>', 'Comma-separated: hot, warm, cold, follow_up, do_not_contact, none')
   .option('--favorites', 'Only starred prospects')
   .option('--list <listId>', 'Only members of this list')
   .option('--tag <tagId>', 'Only prospects with this tag, e.g. tag_31')
@@ -1658,6 +1663,7 @@ prospectsCmd
 Examples:
   dm prospects list
   dm prospects list --source driving
+  dm prospects list --source-group d4d --added-after 2026-10-01 --status hot,warm
   dm prospects list --lifecycle opportunity --tag tag_31
   dm prospects list --record-type person --search "austin" --json`
   )

tests/commands/prospects.test.ts

@@ -154,3 +154,37 @@ describe('dm prospects status display', () => {
     expect(printed).toContain(label);
   });
 });
+
+// The flags are registered on the real program, so a renamed option or query param fails here.
+describe('dm prospects list attribution filters', () => {
+  it('sends source group, added by, added dates and status as query params', async () => {
+    const { program } = await import('../../src/index.js');
+    fetchMock.mockResolvedValue(
+      jsonResponse(200, {
+        data: [],
+        pagination: { page: 1, per_page: 25, total: 0, has_more: false },
+      })
+    );
+
+    await program.parseAsync([
+      'node', 'dm', 'prospects', 'list',
+      '--source-group', 'd4d',
+      '--added-by', '7,12',
+      '--added-after', '2026-10-01',
+      '--added-before', '2026-10-15T12:00:00Z',
+      '--status', 'hot,none',
+      '--json',
+    ]);
+
+    const [url] = fetchMock.mock.calls.at(-1) as [string, RequestInit];
+    const parsed = new URL(url);
+    expect(parsed.pathname).toMatch(/\/prospects$/);
+    expect(Object.fromEntries(parsed.searchParams)).toEqual({
+      source_group: 'd4d',
+      added_by: '7,12',
+      added_after: '2026-10-01',
+      added_before: '2026-10-15T12:00:00Z',
+      status: 'hot,none',
+    });
+  });
+});