@simplyhomes/sos-sdk
Version:
TypeScript SDK for Simply Homes SoS API v4
207 lines (206 loc) • 21.9 kB
JavaScript
/* tslint:disable */
/* eslint-disable */
/**
* API v4
* Swagger documentation for API v4
*
* The version of the OpenAPI document: 4.0
*
*
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
* https://openapi-generator.tech
* Do not edit the class manually.
*/
import * as runtime from '../runtime';
import { V4MlsListingGetMlsListingsInViewResponseDtoFromJSON, V4MlsListingGetMlsListingsResponseDtoFromJSON, V4MlsListingGetUniqueValuesResponseDtoFromJSON, V4MlsListingRefreshMlsListingReturnDtoFromJSON, V4MlsListingUpdateMlsListingBodyDtoToJSON, V4MlsListingUpdateMlsListingResponseDtoFromJSON, } from '../models/index';
/**
*
*/
export class MLSListingsAPIV4Api extends runtime.BaseAPI {
/**
* Retrieves MLS listings that match the criteria defined in a specific view. Views allow pre-defined filters, sorts, and column selections to be applied consistently. **Use Cases:** - Apply saved filter combinations for consistent results - Share standardized queries across team members - Quickly switch between different listing criteria - Maintain consistent filtering logic across different UI components **View Behavior:** - All filters, sorts, and column selections from the view are applied - Additional query parameters (limit, offset, countOnly) can modify the results - Invalid or non-existent viewIds will return an error **Performance:** Views with complex filters or many joined relations may impact query performance. Use the `countOnly` parameter to quickly get total counts without full data retrieval.
* Get MLS listings with a specific viewId
*/
async v4MlsListingControllerGetMlsListingsInViewV4Raw(requestParameters, initOverrides) {
if (requestParameters['viewId'] == null) {
throw new runtime.RequiredError('viewId', 'Required parameter "viewId" was null or undefined when calling v4MlsListingControllerGetMlsListingsInViewV4().');
}
const queryParameters = {};
if (requestParameters['limit'] != null) {
queryParameters['limit'] = requestParameters['limit'];
}
if (requestParameters['offset'] != null) {
queryParameters['offset'] = requestParameters['offset'];
}
if (requestParameters['countOnly'] != null) {
queryParameters['countOnly'] = requestParameters['countOnly'];
}
const headerParameters = {};
if (this.configuration && this.configuration.apiKey) {
headerParameters["x-api-key"] = await this.configuration.apiKey("x-api-key"); // x-api-key authentication
}
let urlPath = `/v4/mls-listings/viewId/{viewId}`;
urlPath = urlPath.replace(`{${"viewId"}}`, encodeURIComponent(String(requestParameters['viewId'])));
const response = await this.request({
path: urlPath,
method: 'GET',
headers: headerParameters,
query: queryParameters,
}, initOverrides);
return new runtime.JSONApiResponse(response, (jsonValue) => V4MlsListingGetMlsListingsInViewResponseDtoFromJSON(jsonValue));
}
/**
* Retrieves MLS listings that match the criteria defined in a specific view. Views allow pre-defined filters, sorts, and column selections to be applied consistently. **Use Cases:** - Apply saved filter combinations for consistent results - Share standardized queries across team members - Quickly switch between different listing criteria - Maintain consistent filtering logic across different UI components **View Behavior:** - All filters, sorts, and column selections from the view are applied - Additional query parameters (limit, offset, countOnly) can modify the results - Invalid or non-existent viewIds will return an error **Performance:** Views with complex filters or many joined relations may impact query performance. Use the `countOnly` parameter to quickly get total counts without full data retrieval.
* Get MLS listings with a specific viewId
*/
async v4MlsListingControllerGetMlsListingsInViewV4(requestParameters, initOverrides) {
const response = await this.v4MlsListingControllerGetMlsListingsInViewV4Raw(requestParameters, initOverrides);
return await response.value();
}
/**
* **Overview:** Retrieves a paginated list of MLS listings with optional filtering and view-based querying. This endpoint provides access to all MLS listings in the system without organization restrictions. **Authentication:** - Requires valid API key via \'x-api-key\' header **Parameters:** - `viewId` (optional): Apply a predefined view configuration for filtering, sorting, and column selection - `limit` (optional): Maximum number of listings to return (default: 50, max: 1000) - `offset` (optional): Number of listings to skip for pagination (default: 0) - `countOnly` (optional): Return only the total count without listing data (default: false) **Response:** Returns an object containing: - `objects`: Array of MLS listing entities matching the query criteria - `count`: Total number of listings matching the filter (useful for pagination) **Use Cases:** - Display paginated MLS listings in frontend applications - Export MLS data with custom filtering via views - Get total count of available listings for pagination controls - Access all MLS listings regardless of organization (non-multi-tenant)
* Get MLS listings with optional filtering
*/
async v4MlsListingControllerGetMlsListingsV4Raw(requestParameters, initOverrides) {
const queryParameters = {};
if (requestParameters['viewId'] != null) {
queryParameters['viewId'] = requestParameters['viewId'];
}
if (requestParameters['limit'] != null) {
queryParameters['limit'] = requestParameters['limit'];
}
if (requestParameters['offset'] != null) {
queryParameters['offset'] = requestParameters['offset'];
}
if (requestParameters['countOnly'] != null) {
queryParameters['countOnly'] = requestParameters['countOnly'];
}
const headerParameters = {};
if (this.configuration && this.configuration.apiKey) {
headerParameters["x-api-key"] = await this.configuration.apiKey("x-api-key"); // x-api-key authentication
}
let urlPath = `/v4/mls-listings`;
const response = await this.request({
path: urlPath,
method: 'GET',
headers: headerParameters,
query: queryParameters,
}, initOverrides);
return new runtime.JSONApiResponse(response, (jsonValue) => V4MlsListingGetMlsListingsResponseDtoFromJSON(jsonValue));
}
/**
* **Overview:** Retrieves a paginated list of MLS listings with optional filtering and view-based querying. This endpoint provides access to all MLS listings in the system without organization restrictions. **Authentication:** - Requires valid API key via \'x-api-key\' header **Parameters:** - `viewId` (optional): Apply a predefined view configuration for filtering, sorting, and column selection - `limit` (optional): Maximum number of listings to return (default: 50, max: 1000) - `offset` (optional): Number of listings to skip for pagination (default: 0) - `countOnly` (optional): Return only the total count without listing data (default: false) **Response:** Returns an object containing: - `objects`: Array of MLS listing entities matching the query criteria - `count`: Total number of listings matching the filter (useful for pagination) **Use Cases:** - Display paginated MLS listings in frontend applications - Export MLS data with custom filtering via views - Get total count of available listings for pagination controls - Access all MLS listings regardless of organization (non-multi-tenant)
* Get MLS listings with optional filtering
*/
async v4MlsListingControllerGetMlsListingsV4(requestParameters = {}, initOverrides) {
const response = await this.v4MlsListingControllerGetMlsListingsV4Raw(requestParameters, initOverrides);
return await response.value();
}
/**
* Retrieves unique values and their counts for a specified column in the MLS listings table. This endpoint is useful for creating filter dropdowns or understanding the distribution of values in a column. **Use Cases:** - Building dynamic filter interfaces with accurate counts - Understanding data distribution for analytics - Creating autocomplete suggestions with frequency information **Column Examples:** - `simplyretsType`: Property types (RES, COM, etc.) - `simplyretsSubType`: Property sub-types - `simplyretsBedrooms`: Number of bedrooms - `simplyretsAddress`: Property addresses - `type`: MLS listing source type **Pagination:** Use `offset` and `limit` parameters to paginate through large result sets. **View Filtering:** When a `viewId` is provided, unique values are calculated only from listings that match the view\'s filters.
* Get unique values for a specific MLS listing column with counts
*/
async v4MlsListingControllerGetUniqueValuesV4Raw(requestParameters, initOverrides) {
if (requestParameters['column'] == null) {
throw new runtime.RequiredError('column', 'Required parameter "column" was null or undefined when calling v4MlsListingControllerGetUniqueValuesV4().');
}
const queryParameters = {};
if (requestParameters['viewId'] != null) {
queryParameters['viewId'] = requestParameters['viewId'];
}
if (requestParameters['limit'] != null) {
queryParameters['limit'] = requestParameters['limit'];
}
if (requestParameters['offset'] != null) {
queryParameters['offset'] = requestParameters['offset'];
}
const headerParameters = {};
if (this.configuration && this.configuration.apiKey) {
headerParameters["x-api-key"] = await this.configuration.apiKey("x-api-key"); // x-api-key authentication
}
let urlPath = `/v4/mls-listings/unique/{column}`;
urlPath = urlPath.replace(`{${"column"}}`, encodeURIComponent(String(requestParameters['column'])));
const response = await this.request({
path: urlPath,
method: 'GET',
headers: headerParameters,
query: queryParameters,
}, initOverrides);
return new runtime.JSONApiResponse(response, (jsonValue) => V4MlsListingGetUniqueValuesResponseDtoFromJSON(jsonValue));
}
/**
* Retrieves unique values and their counts for a specified column in the MLS listings table. This endpoint is useful for creating filter dropdowns or understanding the distribution of values in a column. **Use Cases:** - Building dynamic filter interfaces with accurate counts - Understanding data distribution for analytics - Creating autocomplete suggestions with frequency information **Column Examples:** - `simplyretsType`: Property types (RES, COM, etc.) - `simplyretsSubType`: Property sub-types - `simplyretsBedrooms`: Number of bedrooms - `simplyretsAddress`: Property addresses - `type`: MLS listing source type **Pagination:** Use `offset` and `limit` parameters to paginate through large result sets. **View Filtering:** When a `viewId` is provided, unique values are calculated only from listings that match the view\'s filters.
* Get unique values for a specific MLS listing column with counts
*/
async v4MlsListingControllerGetUniqueValuesV4(requestParameters, initOverrides) {
const response = await this.v4MlsListingControllerGetUniqueValuesV4Raw(requestParameters, initOverrides);
return await response.value();
}
/**
* # POST /v4/mls-listings/{lid}/refresh ## Overview Refreshes MLS listing data from SimplyRETS API. This endpoint retrieves the latest listing information from the MLS data provider and updates the local record with current market data. ## Authentication Requires API key authentication via the `x-api-key` header. ## Use Cases ### When to Use This Endpoint - **Manual Refresh**: When you need to ensure you have the latest listing data - **Data Sync**: After receiving notifications about listing updates - **Price Updates**: To get the most recent pricing information - **Status Changes**: To check for listing status changes (Active, Pending, Closed, etc.) - **Before Important Operations**: Before making decisions based on listing data ## Parameters ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `lid` | string | Yes | The unique listing identifier (MLS ID) to refresh data for | ## Request Example ```bash curl -X POST \"https://api.simplyhomes.com/v4/mls-listings/1005221/refresh\" \\ -H \"x-api-key: YOUR_API_KEY\" ``` ## MLS Data Refresh Process The refresh operation: 1. **Fetches Latest Data**: Retrieves current listing information from SimplyRETS API 2. **Updates Local Record**: Updates the database with the fresh listing data 3. **Updates Timestamp**: Sets the `updatedAt` timestamp to the current time 4. **Triggers Calculations**: Database triggers automatically recalculate derived fields: - Price comparisons (deltaPrice, deltaPricePercentage) - Extracted fields (simplyretsListPrice, simplyretsStatus, etc.) - Processing status updates if applicable ## What Gets Updated The refresh updates all listing data including: - **Pricing**: List price, original list price, price changes - **Status**: Current listing status (Active, Pending, Closed, etc.) - **Property Details**: Any updates to property characteristics - **Agent Information**: Changes to listing agent details - **Dates**: Modified dates, status change dates - **Photos**: Updated photo URLs if changed - **Remarks**: Updated listing descriptions ## Response Successful refresh returns: - **lid**: The listing ID that was successfully refreshed ## Side Effects After a successful refresh: - **Database Triggers**: Automatic recalculation of derived fields - **Processing Status**: May clear processedAt if significant changes detected - **View Updates**: Filtered views reflect the updated data immediately ## Error Handling The endpoint may return: - **404 Not Found**: If the listing ID doesn\'t exist in SimplyRETS - **500 Internal Server Error**: If there\'s an issue connecting to SimplyRETS API
* Refresh MLS listing data from SimplyRETS
*/
async v4MlsListingControllerRefreshMlsListingV4Raw(requestParameters, initOverrides) {
if (requestParameters['lid'] == null) {
throw new runtime.RequiredError('lid', 'Required parameter "lid" was null or undefined when calling v4MlsListingControllerRefreshMlsListingV4().');
}
const queryParameters = {};
const headerParameters = {};
if (this.configuration && this.configuration.apiKey) {
headerParameters["x-api-key"] = await this.configuration.apiKey("x-api-key"); // x-api-key authentication
}
let urlPath = `/v4/mls-listings/{lid}/refresh`;
urlPath = urlPath.replace(`{${"lid"}}`, encodeURIComponent(String(requestParameters['lid'])));
const response = await this.request({
path: urlPath,
method: 'POST',
headers: headerParameters,
query: queryParameters,
}, initOverrides);
return new runtime.JSONApiResponse(response, (jsonValue) => V4MlsListingRefreshMlsListingReturnDtoFromJSON(jsonValue));
}
/**
* # POST /v4/mls-listings/{lid}/refresh ## Overview Refreshes MLS listing data from SimplyRETS API. This endpoint retrieves the latest listing information from the MLS data provider and updates the local record with current market data. ## Authentication Requires API key authentication via the `x-api-key` header. ## Use Cases ### When to Use This Endpoint - **Manual Refresh**: When you need to ensure you have the latest listing data - **Data Sync**: After receiving notifications about listing updates - **Price Updates**: To get the most recent pricing information - **Status Changes**: To check for listing status changes (Active, Pending, Closed, etc.) - **Before Important Operations**: Before making decisions based on listing data ## Parameters ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `lid` | string | Yes | The unique listing identifier (MLS ID) to refresh data for | ## Request Example ```bash curl -X POST \"https://api.simplyhomes.com/v4/mls-listings/1005221/refresh\" \\ -H \"x-api-key: YOUR_API_KEY\" ``` ## MLS Data Refresh Process The refresh operation: 1. **Fetches Latest Data**: Retrieves current listing information from SimplyRETS API 2. **Updates Local Record**: Updates the database with the fresh listing data 3. **Updates Timestamp**: Sets the `updatedAt` timestamp to the current time 4. **Triggers Calculations**: Database triggers automatically recalculate derived fields: - Price comparisons (deltaPrice, deltaPricePercentage) - Extracted fields (simplyretsListPrice, simplyretsStatus, etc.) - Processing status updates if applicable ## What Gets Updated The refresh updates all listing data including: - **Pricing**: List price, original list price, price changes - **Status**: Current listing status (Active, Pending, Closed, etc.) - **Property Details**: Any updates to property characteristics - **Agent Information**: Changes to listing agent details - **Dates**: Modified dates, status change dates - **Photos**: Updated photo URLs if changed - **Remarks**: Updated listing descriptions ## Response Successful refresh returns: - **lid**: The listing ID that was successfully refreshed ## Side Effects After a successful refresh: - **Database Triggers**: Automatic recalculation of derived fields - **Processing Status**: May clear processedAt if significant changes detected - **View Updates**: Filtered views reflect the updated data immediately ## Error Handling The endpoint may return: - **404 Not Found**: If the listing ID doesn\'t exist in SimplyRETS - **500 Internal Server Error**: If there\'s an issue connecting to SimplyRETS API
* Refresh MLS listing data from SimplyRETS
*/
async v4MlsListingControllerRefreshMlsListingV4(requestParameters, initOverrides) {
const response = await this.v4MlsListingControllerRefreshMlsListingV4Raw(requestParameters, initOverrides);
return await response.value();
}
/**
* ## Update MLS Listing Updates editable fields of an MLS listing identified by its unique listing ID (lid). ### Key Features: - **Mark as Processed**: Set `processedAt` to current timestamp to mark listing as processed - **Auto-clear on Update**: The `processedAt` field is automatically cleared when listing data is updated via cron job - **Partial Updates**: Only include fields you want to update in the request body ### Common Use Cases: 1. **Mark Listing as Processed**: ```json { \"mlsListing\": { \"processedAt\": \"2023-12-01T10:00:00Z\" } } ``` ### URL Structure: `PATCH /v4/mls-listings/{lid}` Where: - `lid` is the unique listing identifier
* Update a specific MLS listing by lid
*/
async v4MlsListingControllerUpdateMlsListingV4Raw(requestParameters, initOverrides) {
if (requestParameters['lid'] == null) {
throw new runtime.RequiredError('lid', 'Required parameter "lid" was null or undefined when calling v4MlsListingControllerUpdateMlsListingV4().');
}
if (requestParameters['v4MlsListingUpdateMlsListingBodyDto'] == null) {
throw new runtime.RequiredError('v4MlsListingUpdateMlsListingBodyDto', 'Required parameter "v4MlsListingUpdateMlsListingBodyDto" was null or undefined when calling v4MlsListingControllerUpdateMlsListingV4().');
}
const queryParameters = {};
const headerParameters = {};
headerParameters['Content-Type'] = 'application/json';
if (this.configuration && this.configuration.apiKey) {
headerParameters["x-api-key"] = await this.configuration.apiKey("x-api-key"); // x-api-key authentication
}
let urlPath = `/v4/mls-listings/{lid}`;
urlPath = urlPath.replace(`{${"lid"}}`, encodeURIComponent(String(requestParameters['lid'])));
const response = await this.request({
path: urlPath,
method: 'PATCH',
headers: headerParameters,
query: queryParameters,
body: V4MlsListingUpdateMlsListingBodyDtoToJSON(requestParameters['v4MlsListingUpdateMlsListingBodyDto']),
}, initOverrides);
return new runtime.JSONApiResponse(response, (jsonValue) => V4MlsListingUpdateMlsListingResponseDtoFromJSON(jsonValue));
}
/**
* ## Update MLS Listing Updates editable fields of an MLS listing identified by its unique listing ID (lid). ### Key Features: - **Mark as Processed**: Set `processedAt` to current timestamp to mark listing as processed - **Auto-clear on Update**: The `processedAt` field is automatically cleared when listing data is updated via cron job - **Partial Updates**: Only include fields you want to update in the request body ### Common Use Cases: 1. **Mark Listing as Processed**: ```json { \"mlsListing\": { \"processedAt\": \"2023-12-01T10:00:00Z\" } } ``` ### URL Structure: `PATCH /v4/mls-listings/{lid}` Where: - `lid` is the unique listing identifier
* Update a specific MLS listing by lid
*/
async v4MlsListingControllerUpdateMlsListingV4(requestParameters, initOverrides) {
const response = await this.v4MlsListingControllerUpdateMlsListingV4Raw(requestParameters, initOverrides);
return await response.value();
}
}