feat(scrape): add login profiles for authenticated scraping (#1617)

Stainless-Generated-From: e28e1d16d8f87075395bc8e99fc1698ed9a138df

Author: stlc-bot

src/context/dev/types/web_scrape_params.py

@@ -31,6 +31,9 @@
     "SharedParamsActionWaitFor",
     "SharedParamsParsers",
     "SharedParamsParsersPdf",
+    "SharedParamsProfile",
+    "SharedParamsProfileExisting",
+    "SharedParamsProfileNew",
     "SharedParamsViewport",
     "TimeoutOpts",
 ]
@@ -309,6 +312,28 @@ class SharedParamsParsers(TypedDict, total=False):
     """PDF page range and OCR."""
 
 
+class SharedParamsProfileExisting(TypedDict, total=False):
+    profile_id: Required[Annotated[str, PropertyInfo(alias="profileId")]]
+    """The ID returned in profile.id by an earlier scrape."""
+
+    type: Required[Literal["existing"]]
+    """Reuse a saved browser profile."""
+
+
+class SharedParamsProfileNew(TypedDict, total=False):
+    identifier: Required[str]
+    """Username or email for the target website."""
+
+    password: Required[str]
+    """Password used to sign in. It is never stored in the profile."""
+
+    type: Required[Literal["new"]]
+    """Sign in and create a browser profile."""
+
+
+SharedParamsProfile: TypeAlias = Union[SharedParamsProfileExisting, SharedParamsProfileNew]
+
+
 class SharedParamsViewport(TypedDict, total=False):
     """Browser size in pixels.
 
@@ -361,6 +386,13 @@ class SharedParams(TypedDict, total=False):
     parsers: SharedParamsParsers
     """Document parsing options."""
 
+    profile: SharedParamsProfile
+    """Create or reuse an authenticated browser profile.
+
+    Requires a paid plan and an HTTPS target. Profiles persist session state, bypass
+    shared caches, and cannot be combined with ZDR, custom headers, or raw bytes.
+    """
+
     settle_animations: Annotated[bool, PropertyInfo(alias="settleAnimations")]
     """Wait for CSS animations to finish before capture.
 

src/context/dev/types/web_scrape_response.py

@@ -26,6 +26,7 @@
     "ProductData",
     "ProductDataProduct",
     "ProductDataProductVariant",
+    "Profile",
     "Screenshot",
     "KeyMetadata",
 ]
@@ -385,6 +386,18 @@ class Product(BaseModel):
     """Explanation of the failure and possible next steps."""
 
 
+class Profile(BaseModel):
+    """
+    Authenticated browser profile used for this scrape, or null when no profile was requested. New and existing profile requests both return the profile ID.
+    """
+
+    id: str
+    """
+    Save this ID after creating a profile, then reuse it as
+    sharedParams.profile.profileId with type "existing".
+    """
+
+
 class Screenshot(BaseModel):
     """Screenshot as a base64 image data URL."""
 
@@ -449,6 +462,12 @@ class WebScrapeResponse(BaseModel):
     product: Product
     """Product details found on the page."""
 
+    profile: Optional[Profile] = None
+    """
+    Authenticated browser profile used for this scrape, or null when no profile was
+    requested. New and existing profile requests both return the profile ID.
+    """
+
     request_id: str
     """Unique ID of this request, also in `X-Request-Id`.
 

tests/api_resources/test_web.py

@@ -312,6 +312,10 @@ def test_method_scrape_with_all_params(self, client: ContextDev) -> None:
                         "start_page": 1,
                     }
                 },
+                "profile": {
+                    "profile_id": "prof_210b9798eb53baa4e69d31c1071cf03d",
+                    "type": "existing",
+                },
                 "settle_animations": True,
                 "theme": "light",
                 "viewport": {
@@ -854,6 +858,10 @@ async def test_method_scrape_with_all_params(self, async_client: AsyncContextDev
                         "start_page": 1,
                     }
                 },
+                "profile": {
+                    "profile_id": "prof_210b9798eb53baa4e69d31c1071cf03d",
+                    "type": "existing",
+                },
                 "settle_animations": True,
                 "theme": "light",
                 "viewport": {