checkout-intents 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

checkout_intents/__init__.py

@@ -29,6 +29,7 @@ from ._exceptions import (
     RateLimitError,
     APITimeoutError,
     BadRequestError,
+    PollTimeoutError,
     APIConnectionError,
     AuthenticationError,
     InternalServerError,
@@ -66,6 +67,7 @@ __all__ = [
     "UnprocessableEntityError",
     "RateLimitError",
     "InternalServerError",
+    "PollTimeoutError",
     "Timeout",
     "RequestOptions",
     "Client",

checkout_intents/_client.py

@@ -48,6 +48,23 @@ ENVIRONMENTS: Dict[str, str] = {
 }
 
 
+def _extract_environment_from_api_key(api_key: str) -> Literal["staging", "production"] | None:
+    """
+    Extracts the environment from a Rye API key.
+    API keys follow the format: RYE/{environment}-{key}
+
+    Args:
+        api_key: The API key to parse
+
+    Returns:
+        The extracted environment ('staging' or 'production'), or None if the format doesn't match
+    """
+    import re
+
+    match = re.match(r"^RYE/(staging|production)-", api_key)
+    return match.group(1) if match else None  # type: ignore[return-value]
+
+
 class CheckoutIntents(SyncAPIClient):
     checkout_intents: checkout_intents.CheckoutIntentsResource
     brands: brands.BrandsResource
@@ -95,7 +112,26 @@ class CheckoutIntents(SyncAPIClient):
             )
         self.api_key = api_key
 
-        self._environment = environment
+        # Auto-infer environment from API key
+        inferred_environment = _extract_environment_from_api_key(api_key)
+
+        # Validate environment option matches API key (if both provided)
+        if is_given(environment) and inferred_environment and environment != inferred_environment:
+            raise CheckoutIntentsError(
+                f"Environment mismatch: API key is for '{inferred_environment}' environment but 'environment' option is set to '{environment}'. Please use an API key that matches your desired environment or omit the 'environment' option to auto-detect from the API key (only auto-detectable with the RYE/{{environment}}-abcdef api key format)."
+            )
+
+        # Use provided environment, or infer from API key, or default to staging
+        resolved_environment: Literal["staging", "production"]
+        if is_given(environment):
+            resolved_environment = cast(Literal["staging", "production"], environment)
+            self._environment = cast(Literal["staging", "production"], environment)
+        elif inferred_environment:
+            resolved_environment = inferred_environment
+            self._environment = inferred_environment
+        else:
+            resolved_environment = "staging"
+            self._environment = "staging"
 
         base_url_env = os.environ.get("CHECKOUT_INTENTS_BASE_URL")
         if is_given(base_url) and base_url is not None:
@@ -108,18 +144,16 @@ class CheckoutIntents(SyncAPIClient):
                 )
 
             try:
-                base_url = ENVIRONMENTS[environment]
+                base_url = ENVIRONMENTS[resolved_environment]
             except KeyError as exc:
-                raise ValueError(f"Unknown environment: {environment}") from exc
+                raise ValueError(f"Unknown environment: {resolved_environment}") from exc
         elif base_url_env is not None:
             base_url = base_url_env
         else:
-            self._environment = environment = "staging"
-
             try:
-                base_url = ENVIRONMENTS[environment]
+                base_url = ENVIRONMENTS[resolved_environment]
             except KeyError as exc:
-                raise ValueError(f"Unknown environment: {environment}") from exc
+                raise ValueError(f"Unknown environment: {resolved_environment}") from exc
 
         super().__init__(
             version=__version__,
@@ -291,7 +325,26 @@ class AsyncCheckoutIntents(AsyncAPIClient):
             )
         self.api_key = api_key
 
-        self._environment = environment
+        # Auto-infer environment from API key
+        inferred_environment = _extract_environment_from_api_key(api_key)
+
+        # Validate environment option matches API key (if both provided)
+        if is_given(environment) and inferred_environment and environment != inferred_environment:
+            raise CheckoutIntentsError(
+                f"Environment mismatch: API key is for '{inferred_environment}' environment but 'environment' option is set to '{environment}'. Please use an API key that matches your desired environment or omit the 'environment' option to auto-detect from the API key (only auto-detectable with the RYE/{{environment}}-abcdef api key format)."
+            )
+
+        # Use provided environment, or infer from API key, or default to staging
+        resolved_environment: Literal["staging", "production"]
+        if is_given(environment):
+            resolved_environment = cast(Literal["staging", "production"], environment)
+            self._environment = cast(Literal["staging", "production"], environment)
+        elif inferred_environment:
+            resolved_environment = inferred_environment
+            self._environment = inferred_environment
+        else:
+            resolved_environment = "staging"
+            self._environment = "staging"
 
         base_url_env = os.environ.get("CHECKOUT_INTENTS_BASE_URL")
         if is_given(base_url) and base_url is not None:
@@ -304,18 +357,16 @@ class AsyncCheckoutIntents(AsyncAPIClient):
                 )
 
             try:
-                base_url = ENVIRONMENTS[environment]
+                base_url = ENVIRONMENTS[resolved_environment]
             except KeyError as exc:
-                raise ValueError(f"Unknown environment: {environment}") from exc
+                raise ValueError(f"Unknown environment: {resolved_environment}") from exc
         elif base_url_env is not None:
             base_url = base_url_env
         else:
-            self._environment = environment = "staging"
-
             try:
-                base_url = ENVIRONMENTS[environment]
+                base_url = ENVIRONMENTS[resolved_environment]
             except KeyError as exc:
-                raise ValueError(f"Unknown environment: {environment}") from exc
+                raise ValueError(f"Unknown environment: {resolved_environment}") from exc
 
         super().__init__(
             version=__version__,

checkout_intents/_exceptions.py

@@ -15,6 +15,7 @@ __all__ = [
     "UnprocessableEntityError",
     "RateLimitError",
     "InternalServerError",
+    "PollTimeoutError",
 ]
 
 
@@ -106,3 +107,36 @@ class RateLimitError(APIStatusError):
 
 class InternalServerError(APIStatusError):
     pass
+
+
+class PollTimeoutError(CheckoutIntentsError):
+    """Raised when a polling operation times out before the condition is met."""
+
+    intent_id: str
+    attempts: int
+    poll_interval: float
+    max_attempts: int
+
+    def __init__(
+        self,
+        *,
+        intent_id: str,
+        attempts: int,
+        poll_interval: float,
+        max_attempts: int,
+        message: str | None = None,
+    ) -> None:
+        self.intent_id = intent_id
+        self.attempts = attempts
+        self.poll_interval = poll_interval
+        self.max_attempts = max_attempts
+
+        if message is None:
+            total_time_s = max_attempts * poll_interval
+            message = (
+                f"Polling timeout for checkout intent '{intent_id}': "
+                f"condition not met after {attempts} attempts ({total_time_s}s). "
+                f"Consider increasing max_attempts, polling_interval_ms, or checking the intent state manually."
+            )
+
+        super().__init__(message)

checkout_intents/_models.py

@@ -251,21 +251,22 @@ class BaseModel(pydantic.BaseModel):
         # pydantic version they are currently using
 
         @override
-        def model_dump(
+        def model_dump(  # type: ignore[override]  # pyright: ignore[reportIncompatibleMethodOverride]
             self,
             *,
             mode: Literal["json", "python"] | str = "python",
             include: IncEx | None = None,
             exclude: IncEx | None = None,
+            context: Any | None = None,
             by_alias: bool | None = None,
             exclude_unset: bool = False,
             exclude_defaults: bool = False,
             exclude_none: bool = False,
+            exclude_computed_fields: bool = False,
             round_trip: bool = False,
             warnings: bool | Literal["none", "warn", "error"] = True,
-            context: dict[str, Any] | None = None,
-            serialize_as_any: bool = False,
             fallback: Callable[[Any], Any] | None = None,
+            serialize_as_any: bool = False,
         ) -> dict[str, Any]:
             """Usage docs: https://docs.pydantic.dev/2.4/concepts/serialization/#modelmodel_dump
 
@@ -273,16 +274,24 @@ class BaseModel(pydantic.BaseModel):
 
             Args:
                 mode: The mode in which `to_python` should run.
-                    If mode is 'json', the dictionary will only contain JSON serializable types.
-                    If mode is 'python', the dictionary may contain any Python objects.
-                include: A list of fields to include in the output.
-                exclude: A list of fields to exclude from the output.
+                    If mode is 'json', the output will only contain JSON serializable types.
+                    If mode is 'python', the output may contain non-JSON-serializable Python objects.
+                include: A set of fields to include in the output.
+                exclude: A set of fields to exclude from the output.
+                context: Additional context to pass to the serializer.
                 by_alias: Whether to use the field's alias in the dictionary key if defined.
-                exclude_unset: Whether to exclude fields that are unset or None from the output.
-                exclude_defaults: Whether to exclude fields that are set to their default value from the output.
-                exclude_none: Whether to exclude fields that have a value of `None` from the output.
-                round_trip: Whether to enable serialization and deserialization round-trip support.
-                warnings: Whether to log warnings when invalid fields are encountered.
+                exclude_unset: Whether to exclude fields that have not been explicitly set.
+                exclude_defaults: Whether to exclude fields that are set to their default value.
+                exclude_none: Whether to exclude fields that have a value of `None`.
+                exclude_computed_fields: Whether to exclude computed fields.
+                    While this can be useful for round-tripping, it is usually recommended to use the dedicated
+                    `round_trip` parameter instead.
+                round_trip: If True, dumped values should be valid as input for non-idempotent types such as Json[T].
+                warnings: How to handle serialization errors. False/"none" ignores them, True/"warn" logs errors,
+                    "error" raises a [`PydanticSerializationError`][pydantic_core.PydanticSerializationError].
+                fallback: A function to call when an unknown value is encountered. If not provided,
+                    a [`PydanticSerializationError`][pydantic_core.PydanticSerializationError] error is raised.
+                serialize_as_any: Whether to serialize fields with duck-typing serialization behavior.
 
             Returns:
                 A dictionary representation of the model.
@@ -299,6 +308,8 @@ class BaseModel(pydantic.BaseModel):
                 raise ValueError("serialize_as_any is only supported in Pydantic v2")
             if fallback is not None:
                 raise ValueError("fallback is only supported in Pydantic v2")
+            if exclude_computed_fields != False:
+                raise ValueError("exclude_computed_fields is only supported in Pydantic v2")
             dumped = super().dict(  # pyright: ignore[reportDeprecated]
                 include=include,
                 exclude=exclude,
@@ -311,19 +322,21 @@ class BaseModel(pydantic.BaseModel):
             return cast("dict[str, Any]", json_safe(dumped)) if mode == "json" else dumped
 
         @override
-        def model_dump_json(
+        def model_dump_json(  # type: ignore[override]  # pyright: ignore[reportIncompatibleMethodOverride]
             self,
             *,
             indent: int | None = None,
+            ensure_ascii: bool = False,
             include: IncEx | None = None,
             exclude: IncEx | None = None,
+            context: Any | None = None,
             by_alias: bool | None = None,
             exclude_unset: bool = False,
             exclude_defaults: bool = False,
             exclude_none: bool = False,
+            exclude_computed_fields: bool = False,
             round_trip: bool = False,
             warnings: bool | Literal["none", "warn", "error"] = True,
-            context: dict[str, Any] | None = None,
             fallback: Callable[[Any], Any] | None = None,
             serialize_as_any: bool = False,
         ) -> str:
@@ -355,6 +368,10 @@ class BaseModel(pydantic.BaseModel):
                 raise ValueError("serialize_as_any is only supported in Pydantic v2")
             if fallback is not None:
                 raise ValueError("fallback is only supported in Pydantic v2")
+            if ensure_ascii != False:
+                raise ValueError("ensure_ascii is only supported in Pydantic v2")
+            if exclude_computed_fields != False:
+                raise ValueError("exclude_computed_fields is only supported in Pydantic v2")
             return super().json(  # type: ignore[reportDeprecated]
                 indent=indent,
                 include=include,

checkout_intents/_utils/_compat.py

@@ -34,7 +34,7 @@ def is_typeddict(tp: Type[Any]) -> bool:
 
 
 def is_literal_type(tp: Type[Any]) -> bool:
-    return get_origin(tp) in _LITERAL_TYPES
+    return get_origin(tp) in _LITERAL_TYPES  # type: ignore[comparison-overlap]
 
 
 def parse_date(value: Union[date, StrBytesIntFloat]) -> date:

checkout_intents/_utils/_utils.py

@@ -373,9 +373,9 @@ def get_required_header(headers: HeadersLike, header: str) -> str:
     lower_header = header.lower()
     if is_mapping_t(headers):
         # mypy doesn't understand the type narrowing here
-        for k, v in headers.items():  # type: ignore
-            if k.lower() == lower_header and isinstance(v, str):
-                return v
+        for k, v in headers.items():  # type: ignore[misc, has-type, attr-defined]
+            if k.lower() == lower_header and isinstance(v, str):  # type: ignore[has-type]
+                return v  # type: ignore[has-type]
 
     # to deal with the case where the header looks like Stainless-Event-Id
     intercaps_header = re.sub(r"([^\w])(\w)", lambda pat: pat.group(1) + pat.group(2).upper(), header.capitalize())

checkout_intents/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "checkout_intents"
-__version__ = "0.1.0"  # x-release-please-version
+__version__ = "0.3.0"  # x-release-please-version

checkout_intents/pagination.py

@@ -0,0 +1,89 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import List, Generic, TypeVar, Optional
+from typing_extensions import override
+
+from pydantic import Field as FieldInfo
+
+from ._models import BaseModel
+from ._base_client import BasePage, PageInfo, BaseSyncPage, BaseAsyncPage
+
+__all__ = ["CursorPaginationPageInfo", "SyncCursorPagination", "AsyncCursorPagination"]
+
+_T = TypeVar("_T")
+
+
+class CursorPaginationPageInfo(BaseModel):
+    end_cursor: Optional[str] = FieldInfo(alias="endCursor", default=None)
+
+    has_next_page: Optional[bool] = FieldInfo(alias="hasNextPage", default=None)
+
+    has_previous_page: Optional[bool] = FieldInfo(alias="hasPreviousPage", default=None)
+
+    start_cursor: Optional[str] = FieldInfo(alias="startCursor", default=None)
+
+
+class SyncCursorPagination(BaseSyncPage[_T], BasePage[_T], Generic[_T]):
+    data: List[_T]
+    page_info: Optional[CursorPaginationPageInfo] = FieldInfo(alias="pageInfo", default=None)
+
+    @override
+    def _get_page_items(self) -> List[_T]:
+        data = self.data
+        if not data:
+            return []
+        return data
+
+    @override
+    def next_page_info(self) -> Optional[PageInfo]:
+        if self._options.params.get("before"):
+            start_cursor = None
+            if self.page_info is not None:
+                if self.page_info.start_cursor is not None:
+                    start_cursor = self.page_info.start_cursor
+            if not start_cursor:
+                return None
+
+            return PageInfo(params={"before": start_cursor})
+
+        end_cursor = None
+        if self.page_info is not None:
+            if self.page_info.end_cursor is not None:
+                end_cursor = self.page_info.end_cursor
+        if not end_cursor:
+            return None
+
+        return PageInfo(params={"after": end_cursor})
+
+
+class AsyncCursorPagination(BaseAsyncPage[_T], BasePage[_T], Generic[_T]):
+    data: List[_T]
+    page_info: Optional[CursorPaginationPageInfo] = FieldInfo(alias="pageInfo", default=None)
+
+    @override
+    def _get_page_items(self) -> List[_T]:
+        data = self.data
+        if not data:
+            return []
+        return data
+
+    @override
+    def next_page_info(self) -> Optional[PageInfo]:
+        if self._options.params.get("before"):
+            start_cursor = None
+            if self.page_info is not None:
+                if self.page_info.start_cursor is not None:
+                    start_cursor = self.page_info.start_cursor
+            if not start_cursor:
+                return None
+
+            return PageInfo(params={"before": start_cursor})
+
+        end_cursor = None
+        if self.page_info is not None:
+            if self.page_info.end_cursor is not None:
+                end_cursor = self.page_info.end_cursor
+        if not end_cursor:
+            return None
+
+        return PageInfo(params={"after": end_cursor})

checkout_intents/resources/brands.py

@@ -53,8 +53,8 @@ class BrandsResource(SyncAPIResource):
         """
         Retrieve brand information by domain name
 
-        Look up a brand by its domain name (e.g. "aloyoga.com"). Returns brand
-        information including the marketplace type if the lookup succeeds.
+        Look up a brand by its domain name (e.g. "aloyoga.com" or "www.amazon.com").
+        Returns brand information including the marketplace type if the lookup succeeds.
 
         Args:
           domain: Represents a valid domain name string.
@@ -112,8 +112,8 @@ class AsyncBrandsResource(AsyncAPIResource):
         """
         Retrieve brand information by domain name
 
-        Look up a brand by its domain name (e.g. "aloyoga.com"). Returns brand
-        information including the marketplace type if the lookup succeeds.
+        Look up a brand by its domain name (e.g. "aloyoga.com" or "www.amazon.com").
+        Returns brand information including the marketplace type if the lookup succeeds.
 
         Args:
           domain: Represents a valid domain name string.