Strict typing for walmart/store + lowes/store plugin params

Scrape.do's async-api/plugins page now formally documents the schema
for both `walmart/store` and `lowes/store`. Replace the
`extra="allow"` schema-free passthrough with proper typed fields and
cross-field validators.

WalmartStoreParameters:
- `url` (required, must contain walmart.com)
- `zipcode` + `storeid` conditional pair (both or neither; setting
  only one raises ValidationError)
- gateway-side toggles: disableretry, transparentresponse, timeout
  (5000-120000ms)

LowesStoreParameters:
- `url` (required, must contain lowes.com)
- `zipcode` (required, digits-only)
- `storeid` (required, digits-only)
- same gateway-side toggles as Walmart

Tests:
- tests/unit/async_api/models/plugins/test_additional.py expanded to
  cover every required-field / cross-field / format-validation case.
- tests/unit/async_api/models/plugins/test_discriminated_union.py
  walmart/lowes cases updated to use the new required-field combos.
- Integration plugin sweep re-introduces `google/trends` and
  `lowes/store` now that the pass criterion (`assert_request_accepted`)
  tolerates upstream/engine transient failures. The plugin engine's
  HTTP 400 parameter rejection is still surfaced as a test failure.

Breaking change for callers passing undocumented extras through the
previous schema-free passthrough.

Author: svdC1

.github/CHANGELOG.md

@@ -8,10 +8,16 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Changed
+
+- **`WalmartStoreParameters` / `LowesStoreParameters`** now enforce the documented schema from `Scrape.do's` async-api/plugins page instead of accepting arbitrary extras via `extra="allow"`. Walmart requires `url` (walmart.com domain) and treats `zipcode` + `storeid` as a conditional pair (both or neither). Lowes requires `url` (lowes.com domain) plus digit-only `zipcode` and `storeid`. Both pick up the gateway-side `disableretry` / `transparentresponse` / `timeout` knobs. Breaking change for callers passing undocumented extras through the previous schema-free passthrough.
+
 ### Internal
 
 - Integration suite standardized around three test categories — content-dependent tests retry on transient Scrape.do gateway failures, shape-dependent tests assert only that the request wasn't rejected (HTTP 400), and error-routing tests are unchanged.
 
+- Re-introduced `google/trends` and `lowes/store` into the live plugin sweep now that the pass criterion tolerates upstream / engine-side transient failures.
+
 ## [0.3.0] — 2026-05-24
 
 ### Added

docs/changelog.md

@@ -10,10 +10,16 @@
 
 ## `Unreleased`
 
+### Changed
+
+- **[`WalmartStoreParameters`][scrape_do.async_api.models.plugins.WalmartStoreParameters] / [`LowesStoreParameters`][scrape_do.async_api.models.plugins.LowesStoreParameters]** now enforce the documented schema from `Scrape.do's` async-api/plugins page instead of accepting arbitrary extras via `extra="allow"`. Walmart requires `url` (walmart.com domain) and treats `zipcode` + `storeid` as a conditional pair (both or neither). Lowes requires `url` (lowes.com domain) plus digit-only `zipcode` and `storeid`. Both pick up the gateway-side `disableretry` / `transparentresponse` / `timeout` knobs. Breaking change for callers passing undocumented extras through the previous schema-free passthrough.
+
 ### Internal
 
 - Integration suite standardized around three test categories — content-dependent tests retry on transient Scrape.do gateway failures, shape-dependent tests assert only that the request wasn't rejected (HTTP 400), and error-routing tests are unchanged.
 
+- Re-introduced `google/trends` and `lowes/store` into the live plugin sweep now that the pass criterion tolerates upstream / engine-side transient failures.
+
 ---
 
 ## `0.3.0` — 2026-05-24

src/scrape_do/async_api/models/plugins/additional.py

@@ -20,95 +20,255 @@
 
     - The parameter models live alongside their adapters here
 
-warning: Sparse Documentation
-    - [`Scrape.do's Async API Plugins`](https://scrape.do/documentation/
-    async-api/plugins/) page enumerates the `walmart/store` and `lowes/store`
-    plugin keys, but does NOT formally specify their full schema
-
-    - These plugins return raw HTML rather than structured JSON
-
-    - The models require `geocode` and accept arbitrary additional `key /
-      value` pairs via `extra="allow"` so that callers can construct entries
-      that match whatever shape `Scrape.do` is currently expecting
-      without the SDK blocking on a stale schema
+tip: Output Format
+    Both plugins return raw HTML rather than structured JSON
 
+tip: Official Documentation
+    [`Scrape.do's Async API Plugins`](https://scrape.do/documentation/
+    async-api/plugins/) page formally documents the full parameter
+    schema for `walmart/store` and `lowes/store`
 """
 
 from __future__ import annotations
 
-from typing import List, Literal
+from typing import List, Literal, Optional
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+from typing_extensions import Self
 
 
 class WalmartStoreParameters(BaseModel):
     """Parameters accepted by the `walmart/store` plugin
 
-    warning: Schema-Free
-        - Only `geocode` is documented as required
+    warning: Conditional Pair
+        - `zipcode` and `storeid` are a conditional pair, both must be
+          set or both must be omitted
 
-        - Construct an instance with whatever additional keys the
-          documentation currently lists (extras pass through unchanged
-          thanks to `extra="allow"`)
+        - When both are omitted, `Scrape.do` selects a random Walmart
+          store for the request
 
-        - The plugin returns `raw HTML` rather than structured JSON
+        - Setting only one raises `ValueError`
 
     Attributes:
-        geocode (str): ISO 3166-1 alpha-2 country code selecting the
-            target Walmart marketplace
+        url (str): Walmart product / category URL. Must point to the
+            `walmart.com` domain
+        zipcode (Optional[str]): U.S. zipcode (digits-only). Pairs
+            with `storeid`
+        storeid (Optional[int]): Walmart store ID. Pairs with `zipcode`
+        disableretry (Optional[bool]): Skip `Scrape.do's` internal
+            retry loop on transient failures
+        transparentresponse (Optional[bool]): Return the target's
+            actual status code instead of wrapping non-`2xx` in a `502`
+        timeout (Optional[int]): Per-target timeout in milliseconds
+            (`5000`-`120000`)
 
     Example:
         ```python
         from scrape_do.async_api.models.plugins import WalmartStoreParameters
 
-        param = WalmartStoreParameters(geocode="us", some_extra="value")
+        param = WalmartStoreParameters(
+            url="https://www.walmart.com/ip/123456",
+            zipcode="72712",
+            storeid=100,
+            )
         ```
     """
 
     model_config = ConfigDict(
         populate_by_name=True,
-        extra="allow"
+        extra="ignore",
         )
 
-    geocode: str = Field(
+    url: str = Field(
         ...,
-        alias="geocode"
+        alias="url",
+        )
+    zipcode: Optional[str] = Field(
+        default=None,
+        alias="zipcode",
+        )
+    storeid: Optional[int] = Field(
+        default=None,
+        alias="storeid",
+        )
+    disableretry: Optional[bool] = Field(
+        default=None,
+        alias="disableretry",
         )
+    transparentresponse: Optional[bool] = Field(
+        default=None,
+        alias="transparentresponse",
+        )
+    timeout: Optional[int] = Field(
+        default=None,
+        alias="timeout",
+        ge=5000,
+        le=120000,
+        )
+
+    @field_validator("url")
+    @classmethod
+    def _validate_walmart_domain(cls, value: str) -> str:
+        """Enforces that the URL is a Walmart domain
+
+        Args:
+            value (str): The URL to validate
+
+        Returns:
+            The validated URL unchanged
+
+        Raises:
+            ValueError: If the URL doesn't contain `walmart.com`
+        """
+        if "walmart.com" not in value:
+            raise ValueError(
+                f"`walmart/store` `url` must point to walmart.com,"
+                f" got {value!r}"
+                )
+        return value
+
+    @model_validator(mode="after")
+    def _validate_zipcode_storeid_pair(self) -> Self:
+        """Enforces the documented conditional-pair rule on `zipcode`
+        and `storeid`
+
+        Returns:
+            The validated instance from which the method was called
+
+        Raises:
+            ValueError: If only one of `zipcode` / `storeid` is set
+        """
+        has_zip = self.zipcode is not None
+        has_storeid = self.storeid is not None
+        if has_zip != has_storeid:
+            raise ValueError(
+                "`walmart/store` `zipcode` and `storeid` are a"
+                " conditional pair, set both or omit both"
+                )
+        return self
 
 
 class LowesStoreParameters(BaseModel):
     """Parameters accepted by the `lowes/store` plugin
 
-    warning: Schema-Free
-        - Only `geocode` is documented as required
-
-        - Construct an instance with whatever additional keys the
-          documentation currently lists (extras pass through unchanged
-          thanks to `extra="allow"`)
-
-        - The plugin returns `raw HTML` rather than structured JSON
-
     Attributes:
-        geocode (str): ISO 3166-1 alpha-2 country code selecting the
-            target Lowes marketplace
+        url (str): Lowes product / store URL. Must point to the
+            `lowes.com` domain
+        zipcode (str): U.S. zipcode (digits-only)
+        storeid (str): Lowes store ID (digits-only)
+        disableretry (Optional[bool]): Skip `Scrape.do's` internal
+            retry loop on transient failures
+        transparentresponse (Optional[bool]): Return the target's
+            actual status code instead of wrapping non-`2xx` in a `502`
+        timeout (Optional[int]): Per-target timeout in milliseconds
+            (`5000`-`120000`)
 
     Example:
         ```python
         from scrape_do.async_api.models.plugins import LowesStoreParameters
 
-        param = LowesStoreParameters(geocode="us", some_extra="value")
+        param = LowesStoreParameters(
+            url="https://www.lowes.com/pd/item/123",
+            zipcode="28202",
+            storeid="0595",
+            )
         ```
     """
 
     model_config = ConfigDict(
         populate_by_name=True,
-        extra="allow"
+        extra="ignore",
         )
 
-    geocode: str = Field(
+    url: str = Field(
+        ...,
+        alias="url",
+        )
+    zipcode: str = Field(
+        ...,
+        alias="zipcode",
+        )
+    storeid: str = Field(
         ...,
-        alias="geocode"
+        alias="storeid",
         )
+    disableretry: Optional[bool] = Field(
+        default=None,
+        alias="disableretry",
+        )
+    transparentresponse: Optional[bool] = Field(
+        default=None,
+        alias="transparentresponse",
+        )
+    timeout: Optional[int] = Field(
+        default=None,
+        alias="timeout",
+        ge=5000,
+        le=120000,
+        )
+
+    @field_validator("url")
+    @classmethod
+    def _validate_lowes_domain(cls, value: str) -> str:
+        """Enforces that the URL is a Lowes domain
+
+        Args:
+            value (str): The URL to validate
+
+        Returns:
+            The validated URL unchanged
+
+        Raises:
+            ValueError: If the URL doesn't contain `lowes.com`
+        """
+        if "lowes.com" not in value:
+            raise ValueError(
+                f"`lowes/store` `url` must point to lowes.com,"
+                f" got {value!r}"
+                )
+        return value
+
+    @field_validator("zipcode")
+    @classmethod
+    def _validate_zipcode_digits(cls, value: str) -> str:
+        """Enforces digit-only `zipcode`
+
+        Args:
+            value (str): The zipcode to validate
+
+        Returns:
+            The validated zipcode unchanged
+
+        Raises:
+            ValueError: If `zipcode` contains non-digit characters
+        """
+        if not value.isdigit():
+            raise ValueError(
+                f"`lowes/store` `zipcode` must be digits only,"
+                f" got {value!r}"
+                )
+        return value
+
+    @field_validator("storeid")
+    @classmethod
+    def _validate_storeid_digits(cls, value: str) -> str:
+        """Enforces digit-only `storeid`
+
+        Args:
+            value (str): The storeid to validate
+
+        Returns:
+            The validated storeid unchanged
+
+        Raises:
+            ValueError: If `storeid` contains non-digit characters
+        """
+        if not value.isdigit():
+            raise ValueError(
+                f"`lowes/store` `storeid` must be digits only,"
+                f" got {value!r}"
+                )
+        return value
 
 
 class WalmartStoreAsyncPlugin(BaseModel):
@@ -122,18 +282,18 @@ class WalmartStoreAsyncPlugin(BaseModel):
 
     model_config = ConfigDict(
         populate_by_name=True,
-        extra="ignore"
+        extra="ignore",
         )
 
     key: Literal["walmart/store"] = Field(
         default="walmart/store",
-        alias="Key"
+        alias="Key",
         )
     params: List[WalmartStoreParameters] = Field(
         ...,
         alias="Params",
         min_length=1,
-        max_length=1000
+        max_length=1000,
         )
 
 
@@ -148,16 +308,16 @@ class LowesStoreAsyncPlugin(BaseModel):
 
     model_config = ConfigDict(
         populate_by_name=True,
-        extra="ignore"
+        extra="ignore",
         )
 
     key: Literal["lowes/store"] = Field(
         default="lowes/store",
-        alias="Key"
+        alias="Key",
         )
     params: List[LowesStoreParameters] = Field(
         ...,
         alias="Params",
         min_length=1,
-        max_length=1000
+        max_length=1000,
         )