docs(cli): explain International Owner for APP-4581

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}]}'
+```

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);

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 }) }));
+});