pymlsapi 0.1.0__py3-none-any.whl

pymlsapi/resources/account/__init__.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from pymlsapi.async_http import AsyncHttpClient
+from pymlsapi.http import HttpClient
+from pymlsapi.resources.account.billing import AsyncBillingResource, BillingResource
+from pymlsapi.resources.account.keys import AsyncKeysResource, KeysResource
+
+
+class AccountResource:
+    """Synchronous Account, Billing and Keys namespace."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+        self.billing = BillingResource(http)
+        self.keys = KeysResource(http)
+
+    def get_billing_overview(self):
+        return self.billing.get_overview()
+
+    def verify_key(self):
+        keys = self.keys.list()
+        return keys[0] if keys else None
+
+
+class AsyncAccountResource:
+    """Asynchronous Account, Billing and Keys namespace."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+        self.billing = AsyncBillingResource(http)
+        self.keys = AsyncKeysResource(http)
+
+    async def get_billing_overview(self):
+        return await self.billing.get_overview()
+
+    async def verify_key(self):
+        keys = await self.keys.list()
+        return keys[0] if keys else None

pymlsapi/resources/account/billing.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from pymlsapi.async_http import AsyncHttpClient
+from pymlsapi.http import HttpClient
+
+
+class BillingResource:
+    """Synchronous billing and credit operations."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def get_overview(self) -> Dict[str, Any]:
+        """Fetch subscription tier, credit allowances, and usage breakdown."""
+        return self._http.get("/api/billing/overview")
+
+    def create_checkout_session(
+        self,
+        plan_id: Optional[str] = None,
+        topup_credits: Optional[int] = None,
+        success_url: Optional[str] = None,
+        cancel_url: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Create a Stripe checkout session for plan upgrade or top-up credits."""
+        payload: Dict[str, Any] = {}
+        if plan_id:
+            payload["planId"] = plan_id
+        if topup_credits:
+            payload["topupCredits"] = topup_credits
+        if success_url:
+            payload["successUrl"] = success_url
+        if cancel_url:
+            payload["cancelUrl"] = cancel_url
+        return self._http.post("/api/billing/checkout", json=payload)
+
+    def create_portal_session(self) -> Dict[str, Any]:
+        """Generate self-service Stripe Customer Portal URL."""
+        return self._http.post("/api/billing/portal")
+
+
+class AsyncBillingResource:
+    """Asynchronous billing and credit operations."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def get_overview(self) -> Dict[str, Any]:
+        """Fetch subscription tier, credit allowances, and usage breakdown."""
+        return await self._http.get("/api/billing/overview")
+
+    async def create_checkout_session(
+        self,
+        plan_id: Optional[str] = None,
+        topup_credits: Optional[int] = None,
+        success_url: Optional[str] = None,
+        cancel_url: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Create a Stripe checkout session for plan upgrade or top-up credits."""
+        payload: Dict[str, Any] = {}
+        if plan_id:
+            payload["planId"] = plan_id
+        if topup_credits:
+            payload["topupCredits"] = topup_credits
+        if success_url:
+            payload["successUrl"] = success_url
+        if cancel_url:
+            payload["cancelUrl"] = cancel_url
+        return await self._http.post("/api/billing/checkout", json=payload)
+
+    async def create_portal_session(self) -> Dict[str, Any]:
+        """Generate self-service Stripe Customer Portal URL."""
+        return await self._http.post("/api/billing/portal")

pymlsapi/resources/account/keys.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+from pymlsapi.async_http import AsyncHttpClient
+from pymlsapi.http import HttpClient
+
+
+class KeysResource:
+    """Synchronous API key lifecycle and zero-downtime rotation."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(self) -> List[Dict[str, Any]]:
+        """List active and grace-period expiring API keys."""
+        data = self._http.get("/api/keys")
+        return data.get("keys", [])
+
+    def create(self, name: str, env: str = "test") -> Dict[str, Any]:
+        """Create a new live or test API key."""
+        return self._http.post("/api/keys", json={"name": name, "env": env})
+
+    def rotate(self, key_id: str, grace_hours: int = 24) -> Dict[str, Any]:
+        """Rotate key with a 24-hour grace overlap window."""
+        return self._http.post(f"/api/keys/{key_id}/rotate", json={"graceHours": grace_hours})
+
+
+class AsyncKeysResource:
+    """Asynchronous API key lifecycle and zero-downtime rotation."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def list(self) -> List[Dict[str, Any]]:
+        """List active and grace-period expiring API keys."""
+        data = await self._http.get("/api/keys")
+        return data.get("keys", [])
+
+    async def create(self, name: str, env: str = "test") -> Dict[str, Any]:
+        """Create a new live or test API key."""
+        return await self._http.post("/api/keys", json={"name": name, "env": env})
+
+    async def rotate(self, key_id: str, grace_hours: int = 24) -> Dict[str, Any]:
+        """Rotate key with a 24-hour grace overlap window."""
+        return await self._http.post(f"/api/keys/{key_id}/rotate", json={"graceHours": grace_hours})

pymlsapi/resources/content.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from pymlsapi.async_http import AsyncHttpClient
+from pymlsapi.http import HttpClient
+from pymlsapi.models.content import ContentGenerationResponse
+
+
+class ContentResource:
+    """Synchronous context-aware marketing copy generation operations."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def generate(
+        self,
+        mls_id: str,
+        outputs: Optional[List[str]] = None,
+        tone: str = "luxury",
+        social_platforms: Optional[List[str]] = None,
+        target_audience: Optional[str] = None,
+        custom_notes: Optional[str] = None,
+        property_details: Optional[Dict[str, Any]] = None,
+    ) -> ContentGenerationResponse:
+        """Generate context-aware marketing copy across social channels, video scripts, and email."""
+        payload: Dict[str, Any] = {
+            "outputs": outputs
+            or ["social", "email_blast", "video_script", "flyer_bullets", "mls_remarks"],
+            "tone": tone,
+        }
+        if social_platforms:
+            payload["social_platforms"] = social_platforms
+        if target_audience:
+            payload["target_audience"] = target_audience
+        if custom_notes:
+            payload["custom_notes"] = custom_notes
+        if property_details:
+            payload["property_details"] = property_details
+
+        data = self._http.post(f"/v1/listing/{mls_id}/content", json=payload)
+        return ContentGenerationResponse.model_validate(data)
+
+
+class AsyncContentResource:
+    """Asynchronous context-aware marketing copy generation operations."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def generate(
+        self,
+        mls_id: str,
+        outputs: Optional[List[str]] = None,
+        tone: str = "luxury",
+        social_platforms: Optional[List[str]] = None,
+        target_audience: Optional[str] = None,
+        custom_notes: Optional[str] = None,
+        property_details: Optional[Dict[str, Any]] = None,
+    ) -> ContentGenerationResponse:
+        """Generate context-aware marketing copy across social channels, video scripts, and email."""
+        payload: Dict[str, Any] = {
+            "outputs": outputs
+            or ["social", "email_blast", "video_script", "flyer_bullets", "mls_remarks"],
+            "tone": tone,
+        }
+        if social_platforms:
+            payload["social_platforms"] = social_platforms
+        if target_audience:
+            payload["target_audience"] = target_audience
+        if custom_notes:
+            payload["custom_notes"] = custom_notes
+        if property_details:
+            payload["property_details"] = property_details
+
+        data = await self._http.post(f"/v1/listing/{mls_id}/content", json=payload)
+        return ContentGenerationResponse.model_validate(data)

pymlsapi/resources/intelligence.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from pymlsapi.async_http import AsyncHttpClient
+from pymlsapi.http import HttpClient
+from pymlsapi.models.intelligence import PropertyIntelligence
+
+
+class IntelligenceResource:
+    """Synchronous property intelligence and CapEx operations."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def get(
+        self,
+        mls_id: str,
+        include_llm: bool = True,
+        investor_mode: bool = False,
+    ) -> PropertyIntelligence:
+        """Synthesize public records, tax assessment history, and structural CapEx lifespan analysis."""
+        params = {
+            "include_llm": str(include_llm).lower(),
+            "investor_mode": str(investor_mode).lower(),
+        }
+        data = self._http.get(f"/v1/listing/{mls_id}/intelligence", params=params)
+        return PropertyIntelligence.model_validate(data)
+
+
+class AsyncIntelligenceResource:
+    """Asynchronous property intelligence and CapEx operations."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def get(
+        self,
+        mls_id: str,
+        include_llm: bool = True,
+        investor_mode: bool = False,
+    ) -> PropertyIntelligence:
+        """Synthesize public records, tax assessment history, and structural CapEx lifespan analysis."""
+        params = {
+            "include_llm": str(include_llm).lower(),
+            "investor_mode": str(investor_mode).lower(),
+        }
+        data = await self._http.get(f"/v1/listing/{mls_id}/intelligence", params=params)
+        return PropertyIntelligence.model_validate(data)

pymlsapi/resources/listings.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional, Union
+
+from pymlsapi.async_http import AsyncHttpClient
+from pymlsapi.http import HttpClient
+from pymlsapi.models.listings import BaseListing, IngestJob
+from pymlsapi.poller import poll_job_async, poll_job_sync
+
+
+class ListingsResource:
+    """Synchronous MLS listings and ingestion operations."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def get(self, mls_id: str) -> Union[BaseListing, IngestJob]:
+        """Lookup an MLS listing. If not cached, returns an IngestJob in progress."""
+        data = self._http.get(f"/v1/listing/{mls_id}")
+        if "status" in data and data["status"] in ("processing", "queued"):
+            return IngestJob.model_validate(data)
+        return BaseListing.model_validate(data)
+
+    def get_and_wait(
+        self,
+        mls_id: str,
+        timeout_seconds: float = 60.0,
+        poll_interval: float = 2.0,
+        on_progress: Optional[Callable[[IngestJob], None]] = None,
+    ) -> BaseListing:
+        """Fetch listing and automatically poll until ingestion completes."""
+        initial = self.get(mls_id)
+        if isinstance(initial, BaseListing):
+            return initial
+
+        job_id = initial.job_id or (getattr(initial, "job_id", None) or mls_id)
+
+        def fetch_job() -> IngestJob:
+            data = self._http.get(f"/jobs/{job_id}")
+            return IngestJob.model_validate(data)
+
+        def is_done(job: IngestJob) -> bool:
+            return job.status == "completed"
+
+        def is_failed(job: IngestJob) -> bool:
+            return job.status == "failed"
+
+        poll_job_sync(
+            fetch_fn=fetch_job,
+            is_done_fn=is_done,
+            is_failed_fn=is_failed,
+            timeout_seconds=timeout_seconds,
+            initial_interval=poll_interval,
+            on_progress=on_progress,
+        )
+
+        # After completed, fetch normalized listing
+        data = self._http.get(f"/v1/listing/{mls_id}")
+        return BaseListing.model_validate(data)
+
+    def enqueue(
+        self,
+        mls_id: str,
+        download_photos: bool = True,
+        upload_to_r2: bool = True,
+        save_local: bool = False,
+        photos_concurrency: Optional[int] = None,
+        webhook_url: Optional[str] = None,
+    ) -> IngestJob:
+        """Explicitly enqueue background MLS scraping and photo downloading."""
+        payload: Dict[str, Any] = {
+            "mlsId": mls_id,
+            "downloadPhotos": download_photos,
+            "uploadToR2": upload_to_r2,
+            "saveLocal": save_local,
+        }
+        if photos_concurrency is not None:
+            payload["photosConcurrency"] = photos_concurrency
+        if webhook_url:
+            payload["webhookUrl"] = webhook_url
+
+        data = self._http.post("/jobs", json=payload)
+        return IngestJob.model_validate(data)
+
+    def get_job(self, job_id: str) -> IngestJob:
+        """Get live ingestion progress and status."""
+        data = self._http.get(f"/jobs/{job_id}")
+        return IngestJob.model_validate(data)
+
+    def list_jobs(self, limit: int = 20) -> List[IngestJob]:
+        """List recent background ingestion jobs."""
+        data = self._http.get("/jobs", params={"limit": limit})
+        jobs = data.get("jobs", [])
+        return [IngestJob.model_validate(j) for j in jobs]
+
+
+class AsyncListingsResource:
+    """Asynchronous MLS listings and ingestion operations."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def get(self, mls_id: str) -> Union[BaseListing, IngestJob]:
+        """Lookup an MLS listing. If not cached, returns an IngestJob in progress."""
+        data = await self._http.get(f"/v1/listing/{mls_id}")
+        if "status" in data and data["status"] in ("processing", "queued"):
+            return IngestJob.model_validate(data)
+        return BaseListing.model_validate(data)
+
+    async def get_and_wait(
+        self,
+        mls_id: str,
+        timeout_seconds: float = 60.0,
+        poll_interval: float = 2.0,
+        on_progress: Optional[Callable[[IngestJob], None]] = None,
+    ) -> BaseListing:
+        """Fetch listing and automatically poll until ingestion completes."""
+        initial = await self.get(mls_id)
+        if isinstance(initial, BaseListing):
+            return initial
+
+        job_id = initial.job_id or mls_id
+
+        async def fetch_job() -> IngestJob:
+            data = await self._http.get(f"/jobs/{job_id}")
+            return IngestJob.model_validate(data)
+
+        def is_done(job: IngestJob) -> bool:
+            return job.status == "completed"
+
+        def is_failed(job: IngestJob) -> bool:
+            return job.status == "failed"
+
+        await poll_job_async(
+            fetch_fn=fetch_job,
+            is_done_fn=is_done,
+            is_failed_fn=is_failed,
+            timeout_seconds=timeout_seconds,
+            initial_interval=poll_interval,
+            on_progress=on_progress,
+        )
+
+        data = await self._http.get(f"/v1/listing/{mls_id}")
+        return BaseListing.model_validate(data)
+
+    async def enqueue(
+        self,
+        mls_id: str,
+        download_photos: bool = True,
+        upload_to_r2: bool = True,
+        save_local: bool = False,
+        photos_concurrency: Optional[int] = None,
+        webhook_url: Optional[str] = None,
+    ) -> IngestJob:
+        """Explicitly enqueue background MLS scraping and photo downloading."""
+        payload: Dict[str, Any] = {
+            "mlsId": mls_id,
+            "downloadPhotos": download_photos,
+            "uploadToR2": upload_to_r2,
+            "saveLocal": save_local,
+        }
+        if photos_concurrency is not None:
+            payload["photosConcurrency"] = photos_concurrency
+        if webhook_url:
+            payload["webhookUrl"] = webhook_url
+
+        data = await self._http.post("/jobs", json=payload)
+        return IngestJob.model_validate(data)
+
+    async def get_job(self, job_id: str) -> IngestJob:
+        """Get live ingestion progress and status."""
+        data = await self._http.get(f"/jobs/{job_id}")
+        return IngestJob.model_validate(data)
+
+    async def list_jobs(self, limit: int = 20) -> List[IngestJob]:
+        """List recent background ingestion jobs."""
+        data = await self._http.get("/jobs", params={"limit": limit})
+        jobs = data.get("jobs", [])
+        return [IngestJob.model_validate(j) for j in jobs]

pymlsapi/resources/studio/__init__.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from pymlsapi.async_http import AsyncHttpClient
+from pymlsapi.http import HttpClient
+from pymlsapi.resources.studio.creatives import AsyncCreativesResource, CreativesResource
+from pymlsapi.resources.studio.custom import AsyncCustomResource, CustomResource
+from pymlsapi.resources.studio.enhance import AsyncEnhanceResource, EnhanceResource
+from pymlsapi.resources.studio.floorplan import AsyncFloorPlanResource, FloorPlanResource
+from pymlsapi.resources.studio.jobs import AsyncStudioJobsResource, StudioJobsResource
+from pymlsapi.resources.studio.render import AsyncRenderResource, RenderResource
+from pymlsapi.resources.studio.social import AsyncSocialResource, SocialResource
+from pymlsapi.resources.studio.staging import AsyncStagingResource, StagingResource
+from pymlsapi.resources.studio.upload import AsyncUploadResource, UploadResource
+from pymlsapi.resources.studio.video import AsyncVideoResource, VideoResource
+
+
+class StudioResource:
+    """Aggregated Studio Visual AI namespace."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+        self.jobs = StudioJobsResource(http)
+        self.staging = StagingResource(http, self.jobs)
+        self.enhance = EnhanceResource(http, self.jobs)
+        self.floorplan = FloorPlanResource(http, self.jobs)
+        self.render = RenderResource(http, self.jobs)
+        self.creatives = CreativesResource(http, self.jobs)
+        self.social = SocialResource(http)
+        self.video = VideoResource(http, self.jobs)
+        self.custom = CustomResource(http, self.jobs)
+        self._upload = UploadResource(http)
+
+    def upload(self, *args, **kwargs):
+        """Upload image or video file directly to mlsapi CDN."""
+        return self._upload.upload(*args, **kwargs)
+
+
+class AsyncStudioResource:
+    """Aggregated Asynchronous Studio Visual AI namespace."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+        self.jobs = AsyncStudioJobsResource(http)
+        self.staging = AsyncStagingResource(http, self.jobs)
+        self.enhance = AsyncEnhanceResource(http, self.jobs)
+        self.floorplan = AsyncFloorPlanResource(http, self.jobs)
+        self.render = AsyncRenderResource(http, self.jobs)
+        self.creatives = AsyncCreativesResource(http, self.jobs)
+        self.social = AsyncSocialResource(http)
+        self.video = AsyncVideoResource(http, self.jobs)
+        self.custom = AsyncCustomResource(http, self.jobs)
+        self._upload = AsyncUploadResource(http)
+
+    async def upload(self, *args, **kwargs):
+        """Upload image or video file directly to mlsapi CDN."""
+        return await self._upload.upload(*args, **kwargs)

pymlsapi/resources/studio/creatives.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional
+
+from pymlsapi.async_http import AsyncHttpClient
+from pymlsapi.http import HttpClient
+from pymlsapi.models.studio import AdCreativesResult, StudioJob
+from pymlsapi.resources.studio.jobs import AsyncStudioJobsResource, StudioJobsResource
+
+
+class CreativesResource:
+    """Synchronous branded real estate multi-placement ad creative generation."""
+
+    def __init__(self, http: HttpClient, jobs: StudioJobsResource) -> None:
+        self._http = http
+        self._jobs = jobs
+
+    def generate(
+        self,
+        mls_id: str,
+        trigger: str = "just_listed",
+        direction: str = "magazine",
+        placements: Optional[List[str]] = None,
+        brand_kit: Optional[Dict[str, Any]] = None,
+        webhook_url: Optional[str] = None,
+    ) -> StudioJob:
+        payload: Dict[str, Any] = {
+            "mls_id": mls_id,
+            "trigger": trigger,
+            "direction": direction,
+            "placements": placements or ["feed_portrait", "square", "link", "flyer"],
+        }
+        if brand_kit:
+            payload["brand_kit"] = brand_kit
+        if webhook_url:
+            payload["webhook_url"] = webhook_url
+        data = self._http.post("/v1/studio/creatives/generate", json=payload)
+        return StudioJob.model_validate(data)
+
+    def generate_and_wait(
+        self,
+        mls_id: str,
+        trigger: str = "just_listed",
+        direction: str = "magazine",
+        placements: Optional[List[str]] = None,
+        brand_kit: Optional[Dict[str, Any]] = None,
+        webhook_url: Optional[str] = None,
+        timeout_seconds: float = 90.0,
+        poll_interval: float = 2.0,
+        on_progress: Optional[Callable[[StudioJob], None]] = None,
+    ) -> AdCreativesResult:
+        job = self.generate(
+            mls_id=mls_id,
+            trigger=trigger,
+            direction=direction,
+            placements=placements,
+            brand_kit=brand_kit,
+            webhook_url=webhook_url,
+        )
+        completed = self._jobs.wait_for(
+            job.job_id,
+            timeout_seconds=timeout_seconds,
+            poll_interval=poll_interval,
+            on_progress=on_progress,
+        )
+        return AdCreativesResult.model_validate(completed.result or {})
+
+
+class AsyncCreativesResource:
+    """Asynchronous branded real estate multi-placement ad creative generation."""
+
+    def __init__(self, http: AsyncHttpClient, jobs: AsyncStudioJobsResource) -> None:
+        self._http = http
+        self._jobs = jobs
+
+    async def generate(
+        self,
+        mls_id: str,
+        trigger: str = "just_listed",
+        direction: str = "magazine",
+        placements: Optional[List[str]] = None,
+        brand_kit: Optional[Dict[str, Any]] = None,
+        webhook_url: Optional[str] = None,
+    ) -> StudioJob:
+        payload: Dict[str, Any] = {
+            "mls_id": mls_id,
+            "trigger": trigger,
+            "direction": direction,
+            "placements": placements or ["feed_portrait", "square", "link", "flyer"],
+        }
+        if brand_kit:
+            payload["brand_kit"] = brand_kit
+        if webhook_url:
+            payload["webhook_url"] = webhook_url
+        data = await self._http.post("/v1/studio/creatives/generate", json=payload)
+        return StudioJob.model_validate(data)
+
+    async def generate_and_wait(
+        self,
+        mls_id: str,
+        trigger: str = "just_listed",
+        direction: str = "magazine",
+        placements: Optional[List[str]] = None,
+        brand_kit: Optional[Dict[str, Any]] = None,
+        webhook_url: Optional[str] = None,
+        timeout_seconds: float = 90.0,
+        poll_interval: float = 2.0,
+        on_progress: Optional[Callable[[StudioJob], None]] = None,
+    ) -> AdCreativesResult:
+        job = await self.generate(
+            mls_id=mls_id,
+            trigger=trigger,
+            direction=direction,
+            placements=placements,
+            brand_kit=brand_kit,
+            webhook_url=webhook_url,
+        )
+        completed = await self._jobs.wait_for(
+            job.job_id,
+            timeout_seconds=timeout_seconds,
+            poll_interval=poll_interval,
+            on_progress=on_progress,
+        )
+        return AdCreativesResult.model_validate(completed.result or {})