From d8df212401b964e30c4f4d028e34a80c2780e17c Mon Sep 17 00:00:00 2001
From: Ben Tucker <ben@dealmachine.com>
Date: Fri, 30 Oct 2026 12:59:02 -0400
Subject: [PATCH] docs(cli): explain International Owner for APP-4581

---
 docs/commands.md                           |  8 ++++++++
 src/index.ts                               |  8 +++++++-
 tests/commands/publicApiExtensions.test.ts | 10 +++++++++-
 3 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/docs/commands.md b/docs/commands.md
index 04a03d1..5ab282c 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -1332,3 +1332,11 @@ The summary counts changed prospects, prospects already in that lifecycle, and
 records that are not prospects. Bulk archive ends mail and keeps list membership;
 it closes open opportunities unless `--no-cascade` is supplied. A positional
 `prospect_...` ID continues to use the single-prospect operation.
+
+### International Owner
+
+Property search, count and export accept `international_owner` in the `--body` filters array. Use `true` for foreign mailing addresses, `false` to exclude them, or omit the filter for Any. The source is `MailingForeignAddressInd`: Canada (`C`) and other foreign addresses (`Y`) are international; null values and US territories are excluded.
+
+```bash
+dm properties count --body '{"filters":[{"filter_id":"international_owner","value":true}]}'
+```
diff --git a/src/index.ts b/src/index.ts
index 64e9a15..f3bfa10 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -678,10 +678,16 @@ propertiesCmd
     `
 Examples:
   dm properties search --body '{"locations":[{"type":"zip_code","code":"78704"}]}'
+  dm properties search --body '{"filters":[{"filter_id":"international_owner","value":true}]}' --estimate-cost
   dm properties search -f search-query.json --estimate-cost
   dm properties search -f query.json --json             Estimate automatically
   dm properties search -f query.json --json --yes       Run after approval
-  cat query.json | dm properties search --json`
+  cat query.json | dm properties search --json
+
+International Owner: use international_owner in --body filters.
+  true: foreign mailing addresses (Canada and other countries).
+  false: only addresses without a foreign indicator. Omit for Any.
+  Source: MailingForeignAddressInd; US territories are excluded.`
   )
   .action(async (options) => {
     await propertiesSearch(options);
diff --git a/tests/commands/publicApiExtensions.test.ts b/tests/commands/publicApiExtensions.test.ts
index 9551903..5950a9a 100644
--- a/tests/commands/publicApiExtensions.test.ts
+++ b/tests/commands/publicApiExtensions.test.ts
@@ -32,7 +32,7 @@ vi.mock('../../src/lib/output.js', () => ({
 
 import { printJson, printTable } from '../../src/lib/output.js';
 import { peopleGet, peopleIds, peopleSearch, peopleExport } from '../../src/commands/people.js';
-import { propertiesGet, propertiesIds, propertiesSearch, propertiesExport } from '../../src/commands/properties.js';
+import { propertiesGet, propertiesIds, propertiesSearch, propertiesExport, propertiesCount } from '../../src/commands/properties.js';
 import {
   enrichAddress,
   enrichApn,
@@ -590,3 +590,11 @@ describe.each([
     });
   });
 });
+
+
+it.each([true, false])('passes International Owner %s to property counts without changing its meaning', async (value) => {
+  const filters = [{ filter_id: "international_owner", value }];
+  mockParseRequestBody.mockResolvedValue({ filters });
+  await propertiesCount({ body: JSON.stringify({ filters }), json: true });
+  expect(mockApiRequest).toHaveBeenCalledWith("/properties/search/count", expect.objectContaining({ method: "POST", body: expect.objectContaining({ filters }) }));
+});