v0.3.0: Make limit and pagination, user-facing README, logo, us2 origin

DEVELOPMENT.md

@@ -7,6 +7,7 @@ This is a Make custom app in the local project format used by the Make Apps Edit
 - `scripts/generate.mjs` writes every JSON file under `general/`, `connections/`, `modules/`, `webhooks/`, `rpcs/` and `makecomapp.json` from `scripts/params.mjs`, the fixtures in `test/fixtures/` and the shared operation catalog. `scripts/catalog.json` is a vendored copy of the catalog used by the Zapier and n8n apps (`scripts/catalog.sha256` pins it; a test fails on drift) and `scripts/catalog-modules.mjs` translates it into modules, the webhook and the dynamic dropdowns. The generated files are committed. Edit the scripts, then run `node scripts/generate.mjs`.
 - `test/catalog.test.mjs` checks every catalog module (request, output, TCPA flag, billing text, guards, webhook attach and detach).
 - `test/structure.test.mjs` checks the manifest, file links, billing and compliance copy, and that no callback or wallet fields exist.
+- `test/pagination.test.mjs` plays the six paged modules (Search Properties, Get Investor Properties, Find Investors, Get Property Permits, List Search Sessions, Watch New Search Sessions) against a fake BatchData endpoint the way Make pages: it checks the Limit is met, that no request asks for more records than the Limit has left (billing safety), that the whole body is repeated on every page, and the response paths used. `scripts/paging.mjs` builds the directives.
 - `test/replay.test.mjs` renders the request templates with a small IML evaluator (`test/iml.mjs`) and compares the request bodies and output mapping to the n8n and Zapier integrations.
 
 ```
@@ -20,8 +21,8 @@ Node 20 or later. There are no dependencies.
 1. Create a Make account (the organisation that will own the app) and a Make API key with the `apps:read` and `apps:write` scopes.
 2. Install the Make Apps Editor extension in VS Code and open this folder.
 3. Put the API key in `.secrets/apikey` (the folder is git-ignored).
-4. In `makecomapp.json`, set `origins[0].baseUrl` to your zone, for example `https://us1.make.com/api` or `https://eu1.make.com/api`.
-5. Run **Deploy to Make** from the extension. The app is created as a private app with id `batchdata`.
+4. `makecomapp.json` has one documented origin: the private app `batchdata-r6b83g` in organization 3655001 on `https://us2.make.com/api` (Make added the suffix to the name `batchdata`, so the connection and webhook remote names are `batchdata-r6b83g`). To deploy to another zone or organization, copy that entry, change `baseUrl` and `appId`, and clear the `idMapping`.
+5. Run **Deploy to Make** from the extension.
 6. Open the app in Make and run the checks below.
 
 ## What was and was not verified

README.md

@@ -1,66 +1,144 @@
 # BatchData for Make
 
-Use BatchData property data inside Make scenarios: search and look up properties, skip trace owners (V1 and V3, single and batch), reverse skip trace, verify and geocode addresses, check phone numbers, get permits, find investors by buy box, run search sessions and watch property monitors, with polling and instant (webhook) triggers and a generic API call module.
+![BatchData](assets/logo-512.png)
 
-Support: support@batchservice.com
+BatchData gives you property, owner and address data through an API. This app brings it into your Make scenarios, so you can find properties, enrich them with owner contact details, verify addresses and phone numbers, and react to property changes without writing code.
+
+Typical uses:
 
-> **Status: v0.2.0, not yet imported into Make.** It passes its offline tests. Most operations were smoke-tested live through the BatchData API; monitors and the instant trigger were not (see [What was and was not verified](#what-was-and-was-not-verified)).
+- Build a list of properties that match your filters and send it to a spreadsheet, CRM or marketing tool.
+- Look up one address and add the full property record, ownership and sale history to a lead.
+- Find the owner's phone numbers and emails (skip trace) for a property, and check the numbers against Do Not Call and TCPA litigator lists.
+- Clean up addresses before mailing, or turn an address into coordinates.
+- Start a scenario the moment a property you are watching changes.
 
-![BatchData](assets/logo.png)
+Support: support@batchservice.com
 
 ## Connect
 
-1. Create an API token in your BatchData account.
-2. In a BatchData module, click **Add** next to Connection and paste the token.
+1. Sign in to your BatchData account and create an API token. Tokens are available on plans with API access.
+2. In Make, add any BatchData module to a scenario.
+3. Next to **Connection**, click **Add**, paste the token into **API token** and save.
 
-If the token is rejected, create a new one. For help, contact support@batchservice.com.
+If the token is rejected, create a new one and try again. Use a sandbox token to try the app with sample data. Sandbox tokens return mock data and are not billed. Use a production token for real data. If you need help, contact support@batchservice.com.
 
 ## Modules
 
-Billing text is also in each module's description in Make.
-
-| Module | Type | What it does | Billing |
-| --- | --- | --- | --- |
-| Search Properties | Search | Finds properties by location and filters. Up to 100 records per run. | Per record returned (0 is billed as 1) |
-| Get Property Details | Search | Full property data for one address or ID. | Per matched property |
-| Batch Look Up Properties | Search | Full records for up to 100 addresses in one call. | Per matched property |
-| Skip Trace Owner (V1) | Search | Owner contact details, one result per person. | Per matched property |
-| Skip Trace Owner (V3) | Search | Owner contact details, one result per property with a persons list. | Per matched property |
-| Batch Skip Trace Properties (V3) | Search | Up to 100 properties in one call. | Per matched property |
-| Reverse Skip Trace (Phone or Email) | Search | Finds the person behind a phone number or email. | Per matched result |
-| Verify Address / Batch Verify Addresses | Search | Standardizes one or up to 100 US addresses. | Per address |
-| Autocomplete, Geocode, Reverse Geocode | Search | Address suggestions, coordinates, nearest addresses. | This call does not bill property records |
-| Verify Phone Numbers, Check Do Not Call, Check TCPA Litigator | Search | Phone checks. | Per phone number |
-| Get Property Permits | Search | Building permits for one property, one result per permit. | See the module description |
-| Find Investors (Buy Box), Get Investor Properties | Search | Investors who bought near a subject property, and their holdings. | See the module description |
-| List, Create or Advance, Delete Search Session | Search, Action | Persistent search sessions that return only properties not yet delivered. | Create or Advance bills each record delivered |
-| List, Get, Create, Delete Property Monitor | Search, Action | Property monitors with stream delivery (Kinesis or Azure Event Hubs). | According to your BatchData plan |
-| Watch New Search Sessions | Polling trigger | New search sessions on your team. | Does not bill property records |
-| Watch New Properties in a Search Session (Billed) | Polling trigger | New properties delivered by a session. | Every check bills each property delivered |
-| Watch Property Monitor Events (Instant) | Instant trigger | Fires when a property is added to, removed from or changed in a monitor. | According to your BatchData plan |
-| Watch Property Monitor Events with Property Record (Instant, Billed) | Instant trigger | Same, plus the full property record. | Plan billing, plus one property lookup per event |
-| Make an API Call | Universal | Any other BatchData API path. Wallet, asynchronous and monitor create or edit paths are blocked, and so are bodies with callback URL fields. | Follows the endpoint |
-
-### Instant triggers (property monitor events)
-
-Turning a scenario on creates a V2 property subscription whose delivery is the scenario's own Make webhook URL. Turning it off (or deleting the scenario) deletes that subscription. You never enter a callback URL. Each event is `{eventId, propertyId, parcelHash, addressHash, addedToSubscriptionIds, removedFromSubscriptionIds, propertyChangedAt, sentAt}`. The event carries IDs only; use the module with **Property Record** to add the full record (one billed property lookup per event). Use `eventId` to skip repeats.
-
-Limits (also in each trigger's description): up to 5 monitors per team, a monitor cannot be edited after it is created (delete and recreate it), a new monitor can take up to 7 days to start delivering, and delivery is best effort (4 attempts per event). Because of the 5 monitor limit, avoid many scenarios that each create a monitor.
-
-There is no polling "new monitor" trigger in Make: a polling trigger needs a date or an ordered ID on each item, and monitors have neither. Use List Property Monitors on a schedule instead. The Zapier and n8n apps do include one.
+### Properties
 
-## Phone compliance
+| Module | What it does |
+| --- | --- |
+| Search Properties | Finds properties by location and filters such as property type, bedrooms, owner details and prebuilt quick lists. |
+| Get Property Details | Returns the full record for one address, property ID, hash or APN. |
+| Batch Look Up Properties | Returns full records for up to 100 addresses in one call. |
+| Get Property Permits | Returns the building permits for one property, one result per permit. |
+
+### Owner contact
+
+| Module | What it does |
+| --- | --- |
+| Skip Trace Owner (V1) | Owner contact details for a property, one result per person. |
+| Skip Trace Owner (V3) | Owner contact details, one result per property with a list of persons. |
+| Batch Skip Trace Properties (V3) | Skip trace for up to 100 properties in one call. |
+| Reverse Skip Trace (Phone or Email) | Finds the person behind a phone number or email address. |
+| Verify Phone Numbers | Checks whether phone numbers are valid and reachable. |
+| Check Do Not Call | Checks phone numbers against the Do Not Call list. |
+| Check TCPA Litigator | Checks phone numbers against known TCPA litigators. |
+
+### Addresses
+
+| Module | What it does |
+| --- | --- |
+| Verify Address, Batch Verify Addresses | Standardizes and validates one address, or up to 100 US addresses. |
+| Autocomplete Address | Suggests addresses as you type. |
+| Geocode Address | Turns an address into coordinates. |
+| Reverse Geocode (Find Nearby Addresses) | Finds the addresses closest to a set of coordinates. |
+
+### Investors
+
+| Module | What it does |
+| --- | --- |
+| Find Investors (Buy Box) | Finds likely investors for a subject property, based on nearby comparable sales. |
+| Get Investor Properties | Lists the properties an investor holds. |
+
+### Search sessions
+
+A search session remembers what it has already returned, so each run gives you only properties you have not received before.
+
+| Module | What it does |
+| --- | --- |
+| Create or Advance Search Session | Starts a session, or returns the next properties from an existing one. |
+| List Search Sessions | Lists the sessions on your team. |
+| Delete Search Session | Deletes a session. |
+
+### Property monitors
+
+A monitor reports when a property is added to it, removed from it or changed.
+
+| Module | What it does |
+| --- | --- |
+| Create Property Monitor (Stream Delivery) | Creates a monitor that delivers to AWS Kinesis or Azure Event Hubs. |
+| List Property Monitors, Get Property Monitor | Reads your monitors. |
+| Delete Property Monitor | Deletes a monitor. |
 
-Skip trace and phone modules return data only. You are responsible for following the TCPA and Do Not Call rules before you contact anyone. Skip trace removes phone numbers flagged as TCPA litigators unless you switch on **Include phone numbers flagged as TCPA litigators**.
+### Triggers
 
-## What was and was not verified
+| Module | Type | What it does |
+| --- | --- | --- |
+| Watch New Search Sessions | Polling | Runs when a new search session appears on your team. |
+| Watch New Properties in a Search Session (Billed) | Polling | Runs for each new property a session delivers. |
+| Watch Property Monitor Events (Instant) | Instant | Runs when a property is added to, removed from or changed in a monitor. |
+| Watch Property Monitor Events with Property Record (Instant, Billed) | Instant | The same, and adds the full property record to each event. |
+
+### Other
+
+| Module | What it does |
+| --- | --- |
+| Make an API Call | Calls any other BatchData API path with your connection. |
+
+## Limit and paging
+
+Search Properties, Get Investor Properties, Find Investors (Buy Box), Get Property Permits, List Search Sessions and Watch New Search Sessions have a **Limit** field. It is the total number of records you want. Make fetches them in pages of up to 100 and never asks for more than your Limit, so the Limit is also the most you can be billed for in one run. Search Properties and List Search Sessions also have **Skip** to start part-way through the results.
+
+Each record comes out as its own bundle.
+
+## Billing
+
+Your BatchData plan decides what each call costs. Each module's description in Make says how it is billed. In general:
+
+- Search and lookup modules bill per record returned. Set a Limit to cap it.
+- Skip trace modules bill per matched property.
+- Address, phone and compliance checks bill per item checked.
+- Autocomplete, geocoding and the modules that list, get or delete search sessions do not bill property records.
+- Property monitors and the events they deliver are billed according to your BatchData plan.
+- Get Property Permits bills per property requested, not per permit. A Limit above 100 sends more than one request.
+- Watch New Properties in a Search Session (Billed) bills every property it delivers, on every scheduled run.
+- Watch Property Monitor Events with Property Record (Instant, Billed) adds one property lookup per event.
+
+For pricing questions, contact support@batchservice.com.
+
+## Property monitor events
+
+When you turn a scenario on, the instant trigger creates a monitor that delivers to that scenario's own Make webhook. When you turn it off, or delete the scenario, the monitor is deleted. You do not enter a callback URL.
+
+Each event contains the event ID, property ID, address and parcel hashes, the IDs of the monitors that added or removed the property, and the time it changed. It does not contain the property record. Use the module with **Property Record** to add it. Use the event ID to skip repeats.
+
+Good to know:
+
+- You can have up to 5 monitors per team, so avoid many scenarios that each create one.
+- A monitor cannot be edited. Delete it and create a new one.
+- A new monitor can take up to 7 days to start delivering.
+- Delivery is best effort, with 4 attempts per event, so the same event can arrive more than once.
+- Make has no polling trigger for new monitors. Use List Property Monitors on a schedule instead.
+
+## Phone compliance
 
-Verified live (production API, 1 record per call, through the same request shapes the other BatchData integrations use): property search, lookup, skip trace V1 and V3, reverse skip trace (no match), address verify, DNC, permits, investor buy box and properties, geocode, reverse geocode, autocomplete, and the search-session create, list and delete lifecycle.
+Skip trace and phone modules return data only. You are responsible for following the TCPA and Do Not Call rules before you contact anyone. Skip trace leaves out phone numbers flagged as TCPA litigators unless you switch on **Include phone numbers flagged as TCPA litigators**.
 
-Mocked only: property monitors and the instant triggers. The token used gets 403 on the subscription endpoints, so create, list, delete and event delivery need a sandbox token (mock data, no cost, from app.batchdata.com) or a token with that ability.
+## Support
 
-Offline tests (47) check the manifest, file links, copy rules (one support contact, billing text in every module, no callback fields) and the request body, query and output of every module against mocked responses. The offline IML evaluator is a subset of Make's engine, so Make itself has not run these modules; see `DEVELOPMENT.md` for the checks to run after import.
+Email support@batchservice.com.
 
 ## License
 
-The code in this repository is released under the MIT License (see `LICENSE`). The BatchData API and the data it returns are proprietary to BatchData (batchdata.io) and are subject to BatchData's terms of service; the MIT License does not cover them. Support: support@batchservice.com
+The code in this repository is released under the MIT License (see `LICENSE`). The BatchData API and the data it returns are proprietary to BatchData (batchdata.io) and are subject to BatchData's terms of service. Development notes are in `DEVELOPMENT.md`.