@model-match/api 3.43.1 → 3.45.0

package/README.md

@@ -0,0 +1,121 @@
+# @model-match/api
+
+Typed TypeScript client for the ModelMatch API: US mortgage and real-estate market data covering loan officers, agents, companies, branches, lenders, loans, sales and properties, plus your ModelMatch CRM workspace.
+
+- Generated from the API's OpenAPI 3.1 spec, so every route, request and response is typed.
+- Uses `fetch` and runs anywhere it does: Node 18+, browsers, Bun, Deno, edge runtimes.
+- No runtime dependencies.
+
+## Install
+
+```bash
+npm install @model-match/api
+# or: pnpm add / yarn add / bun add
+```
+
+## Configure
+
+```ts
+import { createClient } from "@model-match/api";
+
+createClient({
+	apiKey: process.env.MODELMATCH_API_KEY, // sent as `x-api-key`
+});
+```
+
+`createClient` configures a shared client once at startup. After that, every method uses it.
+
+| Option    | Type                                        | Notes                                                                             |
+| --------- | ------------------------------------------- | --------------------------------------------------------------------------------- |
+| `baseUrl` | `string`                                    | Defaults to `https://api.modelmatch.com`, or the `MMR_API_URL` env var if set.    |
+| `apiKey`  | `string`                                    | Sent as the `x-api-key` header.                                                   |
+| `token`   | `string \| () => string \| Promise<string>` | OAuth bearer token. The function form runs per request, so it can refresh tokens. |
+| `headers` | `Record<string, string>`                    | Extra headers on every request.                                                   |
+
+## Call
+
+Operations are grouped by resource as static methods: `Originators.list`, `Agents.get`, `Loans.analyticsSummary`, `Properties.get` and so on.
+
+```ts
+import { Originators } from "@model-match/api";
+
+const { data: page } = await Originators.list({
+	body: {
+		flatFilters: { state: "CA" },
+		period: "last12Months",
+		sort: [{ field: "volume", order: "desc" }],
+		pagination: { size: 25 },
+	},
+});
+
+// Next page
+const next = await Originators.list({
+	body: {
+		flatFilters: { state: "CA" },
+		pagination: { size: 25, cursor: page?.cursor },
+	},
+});
+
+// One record
+const { data: lo } = await Originators.get({ path: { nmlsId: "1234567" } });
+```
+
+`createClient()` also returns the same classes grouped by resource (`api.originators.list(...)`), if you prefer that style.
+
+## Per-user auth
+
+The shared client holds one credential. When each call acts for a different user, build a client per call and pass it in:
+
+```ts
+import { createApiClient, Originators } from "@model-match/api";
+
+const client = createApiClient({ auth: () => userToken });
+
+await Originators.list({ client, body: { flatFilters: { state: "CA" } } });
+```
+
+A client from `createApiClient` returns errors instead of throwing: you get `{ data, error, response }` back, and `data` is `undefined` when the call fails. Check `error`, or pass `throwOnError: true` to make it throw like the shared client:
+
+```ts
+const client = createApiClient({ auth: () => userToken, throwOnError: true });
+```
+
+## Errors
+
+Calls through the shared client (the one `createClient` configures) throw on any non-2xx response. The thrown value is the parsed error body, for example `{ error: "not_found" }`. A `402` (out of credits) carries `{ error, balance, cost }`.
+
+To handle errors without exceptions on a single call, pass `throwOnError: false`. You then get `{ data, error, response }` back:
+
+```ts
+import { Properties } from "@model-match/api";
+
+const { data, error, response } = await Properties.get({
+	path: { id },
+	throwOnError: false,
+});
+if (error) {
+	console.warn(response?.status, error);
+}
+```
+
+## Tree-shakable entry
+
+`@model-match/api/slim` exports each operation as a standalone function named after its operationId. Bundlers can then drop whatever you don't import:
+
+```ts
+import { getOriginator, listOriginators } from "@model-match/api/slim";
+
+const { data } = await listOriginators({
+	body: { flatFilters: { state: "TX" } },
+});
+```
+
+It shares configuration with the main entry, so call `createClient` from either one.
+
+## OpenAPI spec
+
+The spec this version was generated from ships with the package as `@model-match/api/openapi.json`. Use it to generate a client in another language.
+
+## License
+
+MIT

package/RELEASE_NOTES.md

@@ -0,0 +1,20 @@
+# Release notes
+
+Changes to `@model-match/api` that affect how you use it. Each version is generated from the ModelMatch API's OpenAPI spec, so new endpoints and fields appear in the [API reference](https://docs.modelmatch.com/developers) as they ship.
+
+## 3.45.0
+
+- **Properties: `ownerOccupancy` filter and field.** The assessor's owner-occupancy flag as `owner_occupied`, `probable_owner_occupied` or `not_flagged`, filterable in flat and advanced filters on property search, count, analytics and bulk exports. `ownerOccupied` is unchanged.
+- **Properties: `absenteeOwner` filter and field.** `true` when the owner's mailing address differs from the property address, `false` when it matches, `null` when either is missing. Combine it with a location filter.
+- **Properties: `ownerMailingAddress` on list results.** Previously only on the property detail response.
+
+## 3.44.0
+
+- **No runtime dependencies.** The fetch client is now built into the package instead of coming from `@hey-api/client-fetch`. Exported names are unchanged; `createApiClient` and the `ApiClient` type keep working.
+- **Default `baseUrl` is now `https://api.modelmatch.com`** for both `createClient` and `createApiClient`. Before, `createClient` defaulted to `http://localhost:3001` and `createApiClient` had no default. `baseUrl` and the `MMR_API_URL` environment variable still override it; set one of them if you relied on the localhost default.
+- **Admin-only operations removed.** A few admin endpoints and their types were published by mistake. They were never callable without an admin account and are no longer part of the package.
+- **README and release notes** now ship with the package, and the published `package.json` no longer lists development dependencies or build scripts.
+
+## 3.39.0
+
+- Release notes start with the next version.